TypePad JSON API Introduction

This page describes the design principles underlying the TypePad JSON API. The TypePad JSON API is RESTful where it makes sense and REST-like where it doesn't. If all you want to do is retrieve public data you can do that with just a simple HTTP client library and a JSON parser.

URL Scheme

The TypePad JSON API follows a predictable URL scheme to make it easier to remember where a given endpoint is and to make it easier to implement client libraries for the API.

For those endpoints which represent TypePad data objects, the general URL scheme is /noun/id/sub-resource/filters. A "noun" is the name of the kind of object whose data is being requested, such as "users" or "blogs", while "id" is a string that identifies the specific object to be retrieved.

Sub-resources can either be property endpoints, which return a specific property of the selected object, or action endpoints, which take an HTTP POST request with some set of parameters and perform an action.

For property endpoints that return lists, filters can be applied that constrain which items are returned in the list. For example, the list of posts in a blog might be constrained to only return posts that are within a certain category. Filter keywords are always prefixed with an at sign (@) and can either be boolean, in which case the presence of the keyword alone describes the filter, or parameterized, in which case a parameter is appended after the filter keyword in the URL. Parameterized filters are named with the prefix by- to make them easily distinguishable from boolean filters.

Some endpoints exist to provide special services to API clients and do not follow this convention. Examples are /batch-processor and /browser-upload, whose purpose and usage are described in more detail on their documentation pages.

The full list of available endpoints, along with links to more detailed documentation for each endpoint, is on the main documentation index page.

Representation Formats

Currently the TypePad JSON API supports only JSON as its representation format. Endpoints which accept and return JSON data have a .json suffix appended to their URLs to indicate this. If other representation formats are supported in future these will be distinguished by having a different format suffix.

HTTP Methods

For most endpoints the TypePad JSON API uses the standard HTTP methods to specify what operation is to be performed on the selected object. The HTTP methods used are as follows:

Method Meaning
GET Retrieve an object
HEAD Equivalent to GET, but only the header part of the response is returned. HEAD may be used anywhere that GET is indicated in this documentation, with the same meaning.
POST Submit a new object to a collection, or send a request to an action endpoint.
PUT Replace (i.e. edit) an object.
DELETE Delete an object.
OPTIONS Allows a client to determine which HTTP methods are allowed on a resource without making a actual API request. When a request is recieved with this method, the server will determine what access the authenticated client has and return an Allow header in the response, but will not actually invoke a method on that object.

The list of methods that can be applied to an endpoint along with the more specific meaning each method has for that endpoint are described on each endpoint's own documentation page.

Action Endpoints

Where a particular operation does not map well onto one of the standard HTTP methods, an action endpoint is provided. The action that the endpoint will perform is described in its URL rather than in the HTTP method, so all requests to an action endpoint use the HTTP method POST.

Each action endpoint has its own documented set of request and response parameters, which are listed on that endpoint's own documentation page. These are encoded as a JSON object.

One example of an action endpoint is /blogs/<id>/remove-category, which allows a caller to remove a category from a blog. Action endpoints can be recognized by their naming scheme of a verb followed by a noun, as opposed to property endpoints which are simply nouns.

Safely Editing Resources

When PUT is used to edit an existing resource, it is important to preserve any existing data that is not being edited. To do this, clients should perform updates as follows:

  • Retrieve the resource using GET and note the value of the ETag response header.
  • Make changes to the retrieved data structure, preserving any data that is not being edited.
  • Serialize and PUT the resulting data, setting the If-Match request header to contain the ETag of the data retrieved earlier.
  • item If the server returns a 412 Precondition Failed error, the resource has been edited by another client since it was retrieved, so the client should repeat this process and re-apply the changes to the latest resource data.

For more information about using ETag and If-Match, see Conditional Calls and Caching.

Response Codes

The TypePad JSON API uses the standard set of HTTP response codes to indicate the success or failure of a request and, in the event of failure, the reason for the failure.

For responses indicating errors, the API will include an HTML body describing the error which may include more detail than can be represented by the HTTP status code. This body is intended to aid debugging and is not intended to be a machine-readable part of the API, nor is it intended to be displayed to end-users.

The list below describes the response codes that are currently used. New response codes may be used in future, so clients should be prepared to deal with all possible response codes, perhaps by recognizing only the class of response (the first digit) and acting accordingly.

Status Code HTTP Name Meaning
200 OK The request was successful, and the response body contains the return value of the request.
201 Created For requests that result in the creation of a resource, the request was successful. The response body contains a representation of the created resource, and the URL of the new resource is given in the Location response header field.
204 No Content The request was successful, but there is no return value.
301 Moved Permanently The requested resource is located at a different URL. The new URL is given in the Location response header field. The request should be repeated at the new URL. All future requests for this resource should use the new URL.
302 Found The requested resource can be found at a different URL. The new URL is given in the Location response header field. The request should be repeated at the new URL, but future requests to the original URL may not return the same response in future. The TypePad API uses this response code where user-provided aliases, such as a user's profile alias, are used to access a resource; the target of the redirect is the canonical, unchanging URL for the resource.
304 Not Modified The response is unchanged from the modified date or ETag given in a conditional call. The client should use a cached representation. See Conditional Calls and Caching for more information.
400 Bad Request The client's request was invalid in some way. This may be an HTTP-level error detected by the TypePad web server, or it might be an API-level error detected by the API handler itself. In the latter case, a human-readable description of the problem is often included in the body of the response to aid with debugging.
401 Unauthorized No credentials were provided, or the credentials that were provided are not valid. If the application was attempting to authenticate with an OAuth token previously provisioned for a specific user, this response indicates that the token used is no longer valid, which may be because the user has revoked it, because the user's account no longer exists, or some other reason. The application may choose to remove the token from its datastore and fall back on treating the user as unauthenticated.
403 Forbidden The client does not have access to perform the requested action.
404 Not Found There is no resource at the URL given in the request, or the URL includes a format extension that is not supported for the requested resource.
405 Method Not Allowed The client is not permitted to use the given HTTP request method on this resource.
412 Precondition Failed A conditional call (see Conditional Calls and Caching) failed because a precondition was not satisfied.
413 Request Entity Too Large The body of the request is larger than allowed.
414 Request URI Too Long The request URI is longer than allowed.
415 Unsupported Media Type Returned when the request body is not of the correct type for the endpoint in use. For example, this error will be returned if a client does a PUT call on a .json endpoint with a body that is of type application/xml.

Redirect Responses

The redirect (3xx) response codes in the above table are returned as standard HTTP redirects, but as an optimization on most redirects the response body in addition to all headers except for Location will be set to what would have been returned if the client had requested the URL indicated in the Location header. Clients can detect that this is the case by checking that the value of the Content-Location header matches the Location header; if it does, then this optimisation is in use and the client may use the response body as the response without requesting the target resource. This optimisation is only supported on GET requests.

Clients making use of this optimisation must be careful to still apply HTTP caching rules correctly.

Conditional Calls and Caching

The TypePad API uses the standard HTTP entity tag ("ETag") mechanism for making conditional calls and for validating cached data.

A successful GET request on a resource will, for most resources, include in the response an ETag header giving an entity tag for the current state of the resource.

It is recommended that clients cache responses from the TypePad API along with the entity tag and include in future GET requests the following precondition header:

The entity tag of the cached response. The server will only return a response if the resource state no longer matches the given entity tag.

If the cached result is still valid, the server will return a 304 Not Modified response. The client should use its cached response to satisfy the request.

Clients must also make conditional calls when editing existing resources. This ensures that the call isn't overwriting changes made by another client since the resource was retrieved. To do this, include in PUT requests the following precondition header:

The entity tag of the response whose data was used as the basis for editing. The server will only complete the request if the resource state matches the given entity tag.

If the resource has changed, the server will return a 412 Precondition Failed response. The client might then respond by retrieving the updated resource, re-applying the changes made, and repeating the request with the new version and associated entity tag. The client might also inform the user of the conflict and allow the user to resolve it.

Object Types

A responses from a data endpoint returns a JSON-encoded object conforming to one of the defined object types listed on the main index page. Clients may wish to create local classes representing the object types that they intend to use.

The type of object that each endpoint returns from a GET or expects for POST or PUT is described on that endpoint's documentation page.