General API design principles

API principles

Status: Draft

Working notes:

• Read the Heroku HTTP API design guide
• And the The twelve-factor app methodology for building SaaS
• Use jsonapi.org
• Consider JSON PATCH
• Endpoints are all nouns, use the HTTP actions as verbs.
• All endpoint nouns must always be singular, to match with database tables. Or plural (explanation). The point is they should remain consistent with other APIs from the same team, organisation or whatever.
• Article: Your API versioning is wrong. Conclusion: Use the headers for versioning.
• Cool ideas:
• (for ease of development) Provide a special undocumented "override" URL path for humans, that sets the header appropriately:
• i.e. /api/v2/nodes --> redirects to --> /api/nodes and automatically sets header: api-version: 2
• or /api/nodes?version=2 --> redirects the same as above
• Caution: Don't overload the content-type header.
• (for ease of development) Provide a similar parameter for the Accept headers. The reason for this is to make it easier during development to send a URL to someone non-technical, or who does have the right dev environment set up, but the URL will still works without any special software like curl or browser plugins. Example: /api/nodes?accept=application/json
• Return 2xx status code to indicate the success of the HTTP request
• Return a status field in the content body to indicate the progress of the business domain request
  • Use a "status" field, not a "state" field. Status refers to a progression.

APIs should conform to previously created APIs where that doesn't contradict the principles above.

Where legacy APIs don't follow the principles above, they should be updated to conform as a pre-requisite to any changes.

Minimal JSONAPI examples

Success response:

(the data array is optional, it could be ommitted if the response is always a single object).

Failure response:

Questions

• The response should be valid JSON API. But must the request be JSON API too?

References

• If the examples above seem unnecessarily verbose (even though they have been cut down the most they can be), try JSend instead, it's simpler.
• How to validate JSON API: Take the schema and your JSON, and input them at JSON schema lint

More stuff

https://www.youtube.com/watch?v=aAb7hSCtvGw

Some of the key takeaways:

• An api should be easy to learn, easy to use, hard to misuse
• Continue to write to the API early and often
• Example programs should be exemplary - this code will end up being copied everywhere
• When in doubt, leave it out
• Be consistent - same word means the same thing across the api 
• Documentation matters - reuse is something is easier to say than to do - doing it requires both good design and good documentation
• Do what is customary - obey standard naming conventions - it should feel like one of the core APIs, know the common pitfalls for the language and avoid them