Linky REST¶

Warning

This is a draft.

HAL/HAL-JSON, JSON-LD, and JSON API are unacceptably cumbersome for many REST-like APIs, and existing APIs can’t be made conformant without breaking changes.

Example problems:

JSON API requires putting all of the resource data under a data key, which is awkward and always a breaking change.
HAL uses _embedded and requires clients to understand CURIEs.
HTTP methods can’t be included using any of the three standards.

In the spirit of XKCD #927, here is a new proposal.

Note

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC2119.

This standard only defines a _links key and a LINK object type. All objects must be instances of this JSON Schema:

type: object
properties:
  _links:
    type: object
    required:
      - rel
      - uri
    properties:
      rel:
        type: string
        minLength: 1
      uri:
        type: string
        pattern: '^/'
      method:
        type: string
        default: GET
        enum:
          - HEAD
          - GET
          - PUT
          - PATCH
          - DELETE
          - POST

{
  "id": "f0JL+2as-Kf",
  "_links": [
    {"rel":  "friend", "iri":  "/person/0JCl+2KH", "method": "GET"}
  ]
}