Standard solution: a secure and documented REST endpoint
The robust recipe for an API call others dare use
§Design resource
- 01Name the address after the thing (noun) not after the action
- 02Choose the right method based on intent — GET retrieves, POST creates, PUT/PATCH modifies, DELETE deletes
- 03Keep readings safe and without side effects
- 04Arrange and document which fields the request and answer contain
§Secure the access
- 01Require login where necessary, and check access on the server with each call
- 02Check lights, indicators and hazard lights.
- 03Never assume the client only sends 'legal' calls
§Validate and respond correctly
- 01Validate all input on the server before it is used or saved
- 02Use parameterised database queries — separate code from data
- 03Answer with a success code (2-series) when successful
- 04Answer with 4-series codes for client errors and 5-series codes for server errors
§Make it useful for others
- 01Provide error messages that can be acted upon without leaking internal information
- 02Document the endpoint — address, method, fields, possible answers
- 03Version so changes don't break existing clients
- 04Consider limiting the number of calls so the endpoint cannot be overloaded