Mailspring/docs/apm-rest-api.md

Atom.io package and update API

This guide describes the web API used by 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 in the settings-view package.

This API should be considered pre-release and is subject to change (though significant breaking changes are unlikely).

Authorization

For calls to the API that require authentication, provide a valid token from your Atom.io account page in the Authorization header.

Media type

All requests that take parameters require application/json.

API Resources

Packages

Listing packages

GET /api/packages

Parameters:

• page (optional)
• sort (optional) - One of downloads, created_at, updated_at, stars. Defaults to downloads
• direction (optional) - asc or desc. Defaults to desc. stars can only be ordered desc

Returns a list of all packages in the following format:

  [
    {
      "releases": {
        "latest": "0.6.0"
      },
      "name": "thedaniel-test-package",
      "repository": {
        "type": "git",
        "url": "https://github.com/thedaniel/test-package"
      }
    },
    ...
  ]

Results are paginated 30 at a time, and links to the next and last pages are provided in the Link header:

Link: <https://www.atom.io/api/packages?page=1>; rel="self",
      <https://www.atom.io/api/packages?page=41>; rel="last",
      <https://www.atom.io/api/packages?page=2>; rel="next"

By default, results are sorted by download count, descending.

Searching packages

GET /api/packages/search

Parameters:

• q (required) - Search query
• page (optional)
• sort (optional) - One of downloads, created_at, updated_at, stars. Defaults to the relevance of the search query.
• direction (optional) - asc or desc. Defaults to desc.

Returns results in the same format as listing packages.

Showing package details

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.

Returns:

  {
    "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)
      ...,
    ]
  }

Creating a package

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

Deleting a package

DELETE /api/packages/:package_name

Delete a package; requires authentication.

Returns:

• 204 - Success
• 400 - Repository is inaccessible
• 401 - Unauthorized

Renaming a package

Packages are renamed by publishing a new version with the name changed in package.json See Creating a new package version for details.

Requests made to the previous name will forward to the new name.

Package Versions

GET /api/packages/:package_name/versions/:version_name

Returns package.json with dist key added for e.g. tarball download:

  {
    "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. If rename is not true, the name field in package.json must match the current package name.

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.
• rename - Boolean indicating whether this version contains a new name for the package.

Returns

• 201 - Successfully created. Returns created version.
• 400 - Git tag not found / Repository inaccessible / package.json invalid
• 409 - Version exists

Deleting 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

Stars

Listing user stars

GET /api/users/:login/stars

List a user's starred packages.

Return value is similar to GET /api/packages

GET /api/stars

List the authenticated user's starred packages; requires authentication.

Return value is similar to GET /api/packages

Starring a package

POST /api/packages/:name/star

Star a package; requires authentication.

Returns a package.

Unstarring a package

DELETE /api/packages/:name/star

Unstar a package; requires authentication.

Returns 204 No Content.

Listing a package's stargazers

GET /api/packages/:name/stargazers

List the users that have starred a package.

Returns a list of user objects:

[
  {"login":"aperson"},
  {"login":"anotherperson"},
]

Atom updates

Listing Atom updates

GET /api/updates

Atom update feed, following the format expected by 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"
}