From 40b66e8eb33939ed75f37f84da3287a3880f50de Mon Sep 17 00:00:00 2001 From: Daniel Hengeveld Date: Thu, 22 May 2014 12:13:58 -0700 Subject: [PATCH 1/2] add atom.io api docs --- docs/apm-rest-api.md | 189 +++++++++++++++++++++++++++++++++++ docs/publishing-a-package.md | 3 + 2 files changed, 192 insertions(+) create mode 100644 docs/apm-rest-api.md diff --git a/docs/apm-rest-api.md b/docs/apm-rest-api.md new file mode 100644 index 000000000..e714a977f --- /dev/null +++ b/docs/apm-rest-api.md @@ -0,0 +1,189 @@ +## Atom.io package and update API + +This guide describes the web API used by [apm](https://github.com/atom/apm) and +Atom. The vast majority of use cases are met by the `apm` command-line tool, +which does other useful things like incrementing your version in `package.json` +and making sure you have pushed your git tag. In fact, Atom itself shells out to +`apm` rather than hitting the API directly. If you're curious about how Atom +uses `apm`, see the [PackageManager class](https://github.com/atom/settings-view/blob/master/lib/package-manager.coffee) +in the `settings-view` package. + +### Authorization + +For calls to the API that require authentication, provide a valid token from your +[Atom.io account page](https://atom.io/account) in the `Authorization` header. + +### Media type + +All requests that take parameters require `application/json`. + +## Resources + +### Packages + +**GET** /api/packages + +Returns a list of all packages in the following format: +```json + [ + { + "releases": { + "latest": "0.6.0" + }, + "name": "thedaniel-test-package", + "repository": { + "type": "git", + "url": "https://github.com/thedaniel/test-package" + } + }, + ... + ] +``` + +**GET** /api/packages/:package_name + +Returns package details and versions for a single package + +Parameters: + +- **engine** (optional) - Only show packages with versions compatible with this + Atom version. Must be valid [SemVer](http://semver.org). + +Returns: + +```json + { + "releases": { + "latest": "0.6.0" + }, + "name": "thedaniel-test-package", + "repository": { + "type": "git", + "url": "https://github.com/thedaniel/test-package" + }, + "versions": [ + (see single version output below) + ..., + ] + } +``` + +**POST** /api/packages + +Create a new package; requires authentication. + +The name and version will be fetched from the `package.json` +file in the specified repository. The authenticating user *must* have access +to the indicated repository. + +When a package is created, a release hook is registered with GitHub for package +version creation. + +Parameters: + +- **repository** - String. The repository containing the plugin, in the form "owner/repo" + +Returns: + +- **201** - Successfully created, returns created package. +- **400** - Repository is inaccessible, nonexistent, not an atom package. Possible + error messages include: + - That repo does not exist, isn't an atom package, or atombot does not have access + - The package.json at owner/repo isn't valid +- **409** - A package by that name already exists + + +**DELETE** /api/packages/:package_name + +Delete a package; requires authentication. + +Returns: + +- **204** - Success +- **400** - Repository is inaccessible +- **401** - Unauthorized + +### Package Versions + +**GET** /api/packages/:package_name/versions/:version_name + +Returns `package.json` with `dist` key added for e.g. tarball download: + +```json + { + "bugs": { + "url": "https://github.com/thedaniel/test-package/issues" + }, + "dependencies": { + "async": "~0.2.6", + "pegjs": "~0.7.0", + "season": "~0.13.0" + }, + "description": "Expand snippets matching the current prefix with `tab`.", + "dist": { + "tarball": "https://codeload.github.com/..." + }, + "engines": { + "atom": "*" + }, + "main": "./lib/snippets", + "name": "thedaniel-test-package", + "publishConfig": { + "registry": "https://...", + }, + "repository": { + "type": "git", + "url": "https://github.com/thedaniel/test-package.git" + }, + "version": "0.6.0" + } +``` + + +### Creating a new package version + +**POST** /api/packages/:package_name/versions + +Creates a new package version from a git tag; requires authentication. + +#### Parameters + +- **tag** - A git tag for the version you'd like to create. It's important to note + that the version name will not be taken from the tag, but from the `version` + key in the `package.json` file at that ref. The authenticating user *must* have + access to the package repository. + +#### Returns + +- **201** - Successfully created. Returns created version. +- **400** - Git tag not found / Repository inaccessible +- **409** - Version exists + +### Delete a version + +**DELETE** /api/packages/:package_name/versions/:version_name + +Deletes a package version; requires authentication. + +Note that a version cannot be republished with a different tag if it is deleted. +If you need to delete the latest version of a package for e.g. security reasons, +you'll need to increment the version when republishing. + +Returns 204 No Content + +### Atom updates + +**GET** /api/updates + +Atom update feed, following the format expected by [Squirrel](https://github.com/Squirrel/). + +Returns: + +``` +{ + "name": "0.96.0", + "notes": "[HTML release notes]" + "pub_date": "2014-05-19T15:52:06.000Z", + "url": "https://www.atom.io/api/updates/download" +} +``` diff --git a/docs/publishing-a-package.md b/docs/publishing-a-package.md index e3433ff9a..a5a45b25c 100644 --- a/docs/publishing-a-package.md +++ b/docs/publishing-a-package.md @@ -87,6 +87,8 @@ with a minor release. * Check out [semantic versioning][semver] to learn more about versioning your package releases. +* Consult the [Atom.io package API docs][apm-rest-api] to learn more about how + `apm` works. [atomio]: https://atom.io [github]: https://github.com @@ -95,3 +97,4 @@ with a minor release. [repo-guide]: http://guides.github.com/overviews/desktop [semver]: http://semver.org [your-first-package]: your-first-package.html +[apm-rest-api]: apm-rest-api.md From e6229f614584c79b6ac1a4cf064f2a3dec7ea266 Mon Sep 17 00:00:00 2001 From: Daniel Hengeveld Date: Thu, 22 May 2014 15:45:30 -0700 Subject: [PATCH 2/2] Use h4 for individual methods in apm api doc --- docs/apm-rest-api.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/apm-rest-api.md b/docs/apm-rest-api.md index e714a977f..23de6ca57 100644 --- a/docs/apm-rest-api.md +++ b/docs/apm-rest-api.md @@ -21,7 +21,7 @@ All requests that take parameters require `application/json`. ### Packages -**GET** /api/packages +#### GET /api/packages Returns a list of all packages in the following format: ```json @@ -40,7 +40,7 @@ Returns a list of all packages in the following format: ] ``` -**GET** /api/packages/:package_name +#### GET /api/packages/:package_name Returns package details and versions for a single package @@ -68,7 +68,7 @@ Returns: } ``` -**POST** /api/packages +#### POST /api/packages Create a new package; requires authentication. @@ -93,7 +93,7 @@ Returns: - **409** - A package by that name already exists -**DELETE** /api/packages/:package_name +#### DELETE /api/packages/:package_name Delete a package; requires authentication. @@ -105,7 +105,7 @@ Returns: ### Package Versions -**GET** /api/packages/:package_name/versions/:version_name +#### GET /api/packages/:package_name/versions/:version_name Returns `package.json` with `dist` key added for e.g. tarball download: @@ -142,7 +142,7 @@ Returns `package.json` with `dist` key added for e.g. tarball download: ### Creating a new package version -**POST** /api/packages/:package_name/versions +#### POST /api/packages/:package_name/versions Creates a new package version from a git tag; requires authentication. @@ -161,7 +161,7 @@ Creates a new package version from a git tag; requires authentication. ### Delete a version -**DELETE** /api/packages/:package_name/versions/:version_name +#### DELETE /api/packages/:package_name/versions/:version_name Deletes a package version; requires authentication. @@ -173,7 +173,7 @@ Returns 204 No Content ### Atom updates -**GET** /api/updates +#### GET /api/updates Atom update feed, following the format expected by [Squirrel](https://github.com/Squirrel/).