DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
...
- Best Practices for Designing a Pragmatic RESTful API
- 10 Best Practices for Better RESTful API
- https://github.com/WhiteHouse/api-standards
Use plural nouns but no verbs
| Resource | GET read | POST create | PUT update | DELETE |
| /dags | Returns a list of dags | Create a new dag | Bulk update of dags | Delete all dags |
| /dags/711 | Returns a specific dag | Method not allowed (405) | Updates a specific dag | Deletes a specific dag |
GET method and query parameters should not alter the state
Use PUT, POST and DELETE methods instead of the GET method to alter the state.
Do not use GET for state changes:
Public facing endpoints should return JSON
GET /dags
{
“dag”: {
“id”: “my_dag”,
...
“start_date”: “2012-04-23T18:25:43.511Z”,
…
}
}
Service endpoints should return (tbd)
- Avro or protobuf (to be decided)
...
Content-Type defines the request format.
Accept defines a list of acceptable response formats.
Version your endpoint
Endpoint versioning is mandatory. Use a simple ordinal number and avoid dot notation such as 2.5. If you think a particular functionality is still experimental, version it as such.
...
We might want to maintain an unversioned link that points to the latest version of an endpoint (t.b.d.)
Handle Errors with HTTP status codes
It is hard to work with an API that ignores error handling. Pure returning of a HTTP 500 with a stacktrace is not very helpful.
Use HTTP status codes
The HTTP standard provides over 70 status codes to describe the return values. We don’t need them all, but there should be used at least a mount of 10.
...
500 – Internal Server Error – API developers should avoid this error. If an error occurs in the global catch blog, the stracktrace should be logged and not returned as response.
Use error payloads
All exceptions should be mapped in an error payload.
Provide authentication for your endpoint
work in progress
Public facing endpoints
- Standard (web) authentication methods
- Kerberos
Internal endpoints
- Kerberos
- None
- Simple
- OAUTH2