strawman1

Strawman Example #1

This is intended as a "kitchen-sink" example expressing most of the features mentioned in the original GitHub issue discussion. I've gone used of nested JSON schemas to describe parameters and response data. Also, I'm using URI Templates to describe URLs.

The API being described

For this example I describe the simple API for setting and retrieving localized messages. This is a likely a silly example, but hopefully it's understandable.

---------------------- --------- ------------------------ --------------
Resource               Methods   Representation           Status Codes
---------------------- --------- ------------------------ --------------
/{locale}/{messageId}  GET, PUT  message format (string)  200, 201, 302
/fallback/{locale}     GET, PUT  language format (string) 200, 201
---------------------- --------- ------------------------ --------------

To update or create a new localized message you PUT a string value to it's /{locale}/{messageId} URI. To assign a fallback locale for missing messages, you PUT a locale name to /fallback/{locale}.

JSON Description

{
  resources: [
    {
      id: "LocalizedMessage",
      doc: "A localized message",
      path: "/{language}/{messageId}", // URI template
      methods: {
        GET: {
          doc: "Retrieve a message",
          statusCodes: [ 200, 302 ]
        },
        PUT: {
          doc: "Update or create a message",
          statusCodes: [ 201 ],
          body: { type: "string" },
          examples: [
            {
              path: "/en_US/greeting",
              body: "Hello, world!"
            },
          ]
        }
      },
      parameters: {
        locale: {
          type: "string",
          pattern: "[a-z]+(_[A-Z]+)?(\\.[a-z-]+)?"
        },
        messageId: {
          type: "string",
          pattern: "[a-z_]+"
        }
      },
      representations: ['application/json', 'text/plain'],
      schema: { type: "string" },
    },
    {
      // This resource has no human-readable documentation, but still provides some info on how to use it.
      id: "FallbackLocale",
      methods: {
        GET: { statusCodes: [ 200 ] },
        PUT: { statusCodes: [ 201 ] }
      },
      parameters: {
        locale: {
          type: "string",
          pattern: "[a-z]+(_[A-Z]+)?(\\.[a-z-]+)?"
        }
      }
    }
  ]
}

Questions/Ideas:

• I like the noun/verb delineation of resources and methods, but perhaps it's too verbose?
• What do others think of URI templates? The specification defines "levels", where level 1 is simple string substitution + URL encoding, and levels 2 and 3 add more features (such as expressing query parameters and hash-fragment URL portions). I feel that requiring at least level 1 templates is not too onerous a burden for implementations.
• What do others think of JSON schema? There's a fair bit of tooling built for it already and it would allow a client to validate (JSON) request bodies before sending them, as well as responses. The trade-off is that it's JSON-only, so some sort of tool for translating schemas to other serialization formats might be desirable.
• There's a lot of schemas defined in-line here. For a larger API where certain parameters are likely to be repeated, it would be nice to provide hyperlinks instead.
• Stating that a URI parameter is a string is redundant.
• What things MUST vs. SHOULD be provided?
• Hyperlinks to representation definitions in addition to known mime-types?