Documentation requirements

Documentation URLs

Documentation base URL

The documentation base URL SHOULD be the same as API’s base URL but with /docs appended.

Documentation MAY live on http instead of https.

Documentation URLs

Documentation is RECOMMENDED to live at the following URLs (assuming https://api.platform.com/v1/docs/ as documentation base URL):

  • Resources: https://api.platform.com/v1/docs/resources/{resource-name}
  • Relations: https://api.platform.com/v1/docs/rels/{relation-name}

Further documentation (e.g. deprecations) should go below those. For example:

  • Resource deprecation: https://api.platform.com/v1/docs/rels/{relation-name}/deprecation
  • Resource other: https://api.platform.com/v1/docs/rels/{relation-name}/{detail-subject}
  • Field deprecation: https://api.platform.com/v1/docs/resources/{resource-name}/{field-name}-deprecation

Resource documentation

Contents

The following must be documented for each resource:

  • name

  • description

  • URL template

  • supported methods

  • in which resources it can be embedded

  • whether ETag is supported

  • whether it is deprecated

  • For each linked resource:
    • name
    • description
    • URL template
    • link to resource documentation
    • supported methods
    • whether it can be embedded
    • whether it is deprecated
    • whether it supports zooming
  • A list of all fields with for each field:
    • name
    • description
    • type value (see section [field types](#field-types))
    • format value (see section [field types](#field-types))
    • required?
    • writable?
    • modifiable?

For each deprecation the document MUST describe when the relation/resource/field will no longer be supported.

Field types

The following field types are in use (inspired by but not the same as https://developers.google.com/discovery/v1/type-format):

Type value Format value Meaning
any – The field may have any type. Defined by the JSON Schema spec.
array – A JavaScript array of values. The items field indicates the schema for the array values. Defined by the JSON Schema spec.
boolean – A boolean value, either “true” or “false”. Defined by the JSON Schema spec.
integer int32 A 32-bit signed integer. It has a minimum value of -2,147,483,648 and a maximum value of 2,147,483,647 (inclusive).
integer uint32 A 32-bit unsigned integer. It has a minimum value of 0 and a maximum value of 4,294,967,295 (inclusive).
number double A double-precision 64-bit IEEE 754 floating point.
number float A single-precision 32-bit IEEE 754 floating point.
object – A JavaScript object. Defined by the JSON Schema spec.
string – An arbitrary string. Defined by the JSON Schema spec.
string byte A padded, base64-encoded string of bytes, encoded with a URL and filename safe alphabet (sometimes referred to as “web-safe” or “base64url”). Defined by RFC4648.
string date An ISO8601 date in the format YYYY-MM-DD. Defined in the JSON Schema spec.
string date-time An ISO8601 timestamp in UTC time. This is formatted as YYYY-MM-DDThh:mm:ss.fffZ.
string int64 A 64-bit signed integer. It has a minimum value of -9,223,372,036,854,775,808 and a maximum value of 9,223,372,036,854,775,807 (inclusive).
string uint64 A 64-bit unsigned integer. It has a minimum value of 0 and a maximum value of (2^64)-1 (inclusive).

Getting started guide

API reference

Example code

TODO

  • Integrate: