Appendix E : Atom server-side APIs

Less than 1 minute

STOP

This is being kept for archival purposes only from the original Atom documentation. As this may no longer be relevant to Pulsar, use this at your own risk. Current Pulsar documentation is found at documentation home.

Atom server-side APIs

This appendix covers the the Atom server-side APIs that various parts of Atom consume.

WARNING

Warning: These APIs should be considered pre-release and are subject to change.

Atom package server API

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

WARNING

Warning: This API should be considered pre-release and is subject to change.

Authorization

For calls to the API that require authentication, provide a valid token from your atom.io account pageopen in new window 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

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 SemVeropen in new window.

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.

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 example for 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 update server API

WARNING

Warning: This API should be considered pre-release and is subject to change.

Atom updates

Listing Atom updates
GET /api/updates

Atom update feed, following the format expected by Squirrelopen in new window.

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