Publish API Set Conventions

Publish API Set Conventions

The API endpoints under the /api/publish/v1 URL space follow different conventions than the standards set for all of our APIs moving forward. There are three primary differences:

  • The use of verb-oriented method calls (such as "create") rather than noun-oriented resources (such as "project").
  • A less robust error reporting mechanism returning a single error type and message.
  • Only JSON is supported for request and response bodies.

See below for more details on these conventions.

Naming Conventions

The publish API set uses the following naming conventions for endpoints:

Individual API endpoints are identified by the combination of two identifiers:

  1. version -- The version of the API.  See below for backwards compatibility rules.
  2. method_name -- The name of the API method that you are calling (create, update, list, etc.).  Details for possible API calls can be found in the Working with Projects section of our documentation.

All request endpoints require the use of POST requests, regardless of whether the call results in side-effects on the server.

Standard for Publish Errors

The API calls under the "publish" namespace follows a deprecated standard for error notifications.

In case of an error, there are three types of possible HTTP errors:

  1. HTTP 403 - Indicates that the provided user doesn't have the permissions required to perform the requested action.
  2. HTTP 404 - Indicates that the requested method doesn't exist
  3. HTTP 500 - Indicates that an error occurred while processing the request.

In the case of a 500 Error Response, all calls return a description of the error in the body of the response in JSON format.  The error response will provide enough information for the application to present a reasonable error the end-user.  The format of the JSON is:

    'error_type' : 'ClassOfError',
    'error_value' : 'Human readable string explaining the error'

Your application can provide useful responses to your users based on the error_type returned.  The error_value field is intended for developer information, to explain the exact error.  We do not suggest you show this field directly to your users.  You should provide more user-friendly or internationalized errors than is available in the error_value field.