pulsar/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.

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.

Resources

Packages

GET /api/packages

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

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

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:

  {
    "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

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

POST /api/packages/:name/star

Star a package; requires authentication.

Returns a package.

DELETE /api/packages/:name/star

Unstar a package; requires authentication.

Returns 204 No Content.

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"
}