Skip to content

The JSON Checklist

Sam Harwell edited this page Sep 13, 2013 · 8 revisions

The JSON and REST API Checklist

This checklist is intended to help service developers document their REST APIs in a manner that supports the development of reliable clients.

  • This is merely a checklist. A separate document may be compiled containing the rationale for including each of the items.
  • This is a documentation checklist. Practices regarding considerations for an actual API design or implementation can be separately compiled.

The Basics

  • When looking at a page of the the compiled documentation, do users have a clearly identified location to report documentation errors?
  • Are users able to contribute updates to the documentation? If so, are the project practices for such contributions clearly documented?

Specifications and Vendors

In cooperative development efforts that include multiple companies and/or organizations, APIs may be specified in multiple places. Through this document, the OpenStack and Rackspace specifications will be used to illustrate certain relations that appear in these situations. Ideally, the OpenStack organization provides a base specification which Rackspace, a vendor, supports in its product offerings. OpenStack may also provide an implementation of the specification, which represents a second vendor.

The checklist below applies equally to documentation provided in both the base specification and vendor implementations. However, the answers to certain questions may vary between these documents. If the vendor-specific documentation does not define a superset of the functionality defined in the base specification, then a conflict exists. Conflicts identity situations where an application which strictly adheres to the base specification could encounter unexpected compatibility problems when used with a particular vendor.

Base Specifications

Vendor Implementations

  • Is the base specification identified?
  • Are conflicts between the base specification and the vendor implementation documented?

The REST API Checklist

Methods

  • Does the description of the method clearly state both the synchronous and asynchronous behavior of the method?
    • The synchronous behavior of a method is the behavior that completes before the call returns.
    • The asynchronous behavior of the method is behavior that takes effect sometime after the beginning of the call, but may not complete before the call returns.
  • Is the operation atomic?
  • Is the operation durable?
  • Does the operation provide stronger consistency guarantees than the consistency model of the API as a whole? If so, are they documented for the method?
  • Are the pre- and post-conditions of the method clearly stated?
  • For which, if any, error codes does the system guarantee that the internal state does not change as a result of the call?

Requests

  • Are query parameters documented according to the members section below?

Responses

  • Is the complete set of possible HTTP status codes returned by the call listed?
  • For error codes
    • Is a description provided for each 4xx status code?
    • Does the response body for an error include additional information about the specific error that occurred?
    • What state is the server in following an error?

The JSON Checklist

Conceptual Grouping (Optional Features and/or Extensions)

Products which are developed as an implementation of an open specification frequently include vendor-specific customizations (extensions) to the original specification.

  • Does every optional feature and extension have a distinguishing name?
  • If the extension is specific to a vendor, does the name identify the vendor responsible for the extension?
  • Does the description of the extension include a complete list of new object types which are defined by the extension?
  • Does the description of the extension include a complete list of existing object types (from the underlying specification) which are modified by the extension? For example, members may be added to, removed from, or change in meaning as a result of the vendor supporting the extension.
    • The vendor's documentation for the existing object type should list the members affected by the extension.

Objects

  • Does every object have a named type? This includes JSON objects in both requests and responses.
  • Does every object have a description?
    • If the object may be confused with a similar object elsewhere in the API, is the difference clearly described?

Members

  • Is a description of the member included?
  • If the member is defined by a named optional feature or extension, is the feature identified by name?
  • Can the member be omitted?
  • What values are allowed for the member? JSON supports the values string, number, object, array, true, false, and null.
  • Is the value unique? If so, in what scope is it guaranteed to be unique?
  • If the value can be a number
    • Is the inclusive range (defined below) of values given, when applicable to the value?
    • Is the exclusive range (defined below) of values given, when applicable to the value?
  • If the value can be a string
    • Is the inclusive range of lengths given, when applicable to the value?
    • Is the exclusive range of lengths given, when applicable to the value?
    • Is the inclusive range of supported code points defined, when applicable to the value?
    • Is the exclusive range of supported code points defined, when applicable to the value?
    • Is the value case-sensitive? If not, what language should be used for the case-insensitive comparison?
  • If the value can be an array
    • Is the inclusive range of lengths given, when applicable to the value?
    • Is the exclusive range of lengths given, when applicable to the value?
  • If the value is a reference to another object, is the specific member given? For example, if the member is volume_type, and the Volume Type object includes both members id and name, does the value refer to id or name?
    • For improved maintainability, the referenced member should be explicitly stated even when only one possibility exists. Using the volume_type example, the documentation should explicitly state the value refers to the id member even if the Volume Type object's only member is id.
  • If the value represents a storage size, are the units clearly specified? To eliminate confusion, the exact conversion to bytes should be included where applicable (e.g. if the units are "GB", then GB should be defined as either 2³⁰ or 10⁹ bytes).
  • If the value is a date, what is the allowable format of the date? Formats include, but are not limited to the following:

Exclusive ranges

Exclusive ranges are used where values outside the range are meaningless for the member. For example, if the member describes a completion percentage, the exclusive range 0-100 could be given. Exclusive ranges can also be one-sided, e.g. file sizes have an exclusive range of non-negative numbers.

Inclusive ranges

Inclusive ranges are used where a natural exclusive range does not exist, but clients still need minimum guarantees regarding service support.

If the documentation is being written for a shared specification as opposed to a particular implementation, an inclusive range can be given to help clients ensure cross-provider compatibility. For example, if a member exists as a display description of an entity, the inclusive range could state that all compatible implementations will support descriptions with up to 255 characters (Unicode code points). Individual implementations of the specification are then free to support longer descriptions, and client developers have the option to limit new descriptions to 255 characters to guarantee support for any implementation.

"Text"

To ensure services support users across multiple operating systems and languages, text content can only exist within a well-defined context.

  • Strings within a JSON body use the encoding specified in the HTTP header. Since services may support the Content-Encoding HTTP header and/or the charset property of the Content-Type header, the documentation should clearly state the method users should use for specifying the encoding.
    • Does the server support the Content-Encoding HTTP header for specifying the JSON encoding?
    • Does the server support the charset property of the Content-Type header for specifying the JSON encoding in requests?
    • What encoding(s) does the server support for HTTP requests? While the server MAY support additional encodings, clients SHOULD NOT assume that a particular encoding is supported which was not explicitly listed.
    • What encoding does the server use for replies?
  • If the content of a text file is separately encoded in the JSON body (e.g. using Base 64 encoding), the text encoding cannot be inferred from the HTTP headers. In this case, make sure the following items are defined:
    • What encoding should be used for the text?
    • Is the host system allowed or required to perform line-ending conversions on the body of the text?

The storage requirements of text cannot be measured in bytes unless the encoding is specified. Since the storage architecture may use a different encoding from the HTTP request containing the text, all documentation regarding the storage requirements of text content should be checked for the following.

  • Is the encoding used for determining storage requirements of text content clearly stated?
You can’t perform that action at this time.