News for hackers. Stuff that matters.
Re:Ask HN: What makes an API good? by grosskur on Tuesday October 28, 2014 @12:00PM (#8521635)
The Heroku platform team has a good document about their API design guidelines:

https://github.com/interagent/http-api-design

Re:Ask HN: What makes an API good? by iamdanfox on Tuesday October 28, 2014 @12:47PM (#8521900)
That is a very comprehensive set of conventions! Contents pasted here:

Foundations - Require TLS, Version with Accepts header, Support caching with Etags, Trace requests with Request-Ids, Paginate with ranges

Requests - Return appropriate status codes, Provide full resources where available, Accept serialized JSON in request bodies, Use consistent path formats, Downcase paths and attributes, Support non-id dereferencing for convenience, Minimize path nesting

Responses - Provide resource (UU)IDs, Provide standard timestamps, Use UTC times formatted in ISO8601, Nest foreign key relations, Generate structured errors, Show rate limit status, Keep JSON minified in all responses

Artifacts - Provide machine-readable JSON schema, Provide human-readable docs, Provide executable examples, Describe stability