Requests
It all starts with a request. The request is quite simple: some action on some resource with some parameters. I'd like requests to be easy to make and in a format that is easy to construct.
Endpoints
Endpoints represent resources. Example: /dogs, /cats, /users.
I'm curious if a second endpoint to get a single entity (/dogs/:id) is really needed or if we could just piggy back on the collection endpoint (/dogs?ids=[...]). You get guaranteed consistency since there aren't two endpoints to maintain, plus you can get a whole batch using the ids.
Methods
Instead of inventing new verbs, only the four http methods are used (when applicable): GET, POST, PUT, DELETE. These correspond to "get", "create", "update" and "delete".
Parameters
With GET requests the parameters act as filters for the result. There are certain kinds of filters I think that could be standard, like ids, pagination, sorting, query, and dates. These standard filters could be present on all resources, although the underlying implementations may differ by resource. Then there are other kinds of filters that might be purely resource specific.
With POST the parameters are the data for the resource record being created.
With PUT the parameters are the data you want to update. Obviously you need to include the id of the record you want to update.
With DELETE, I'd imagine there is only one parameter, which would be the id or ids of the record or records you want to delete.
Validation
I can't tolerate the thought of an api that simply sits in the middle of the internet and the database. I think validation should be in there somewhere. I see three areas of validation:
- Authorization
- Who is submitting the request?
- Do they have permission to request this method on this resource?
- Should they be throttled or blocked?
- Request Validation
- Is the requested resource valid?
- Is the request method supported for this resource?
- Are the parameters and values valid?
- Data Validation
- Is the data being submitted valid according to business rules?
- Is the data valid according to the database schema?
Errors
Codes are dandy but I'd also like to get back error messages that can be understood by the application developer and even displayed in the application.
I also think it's annoying when validation processes only return one error message when there could be more. If the user filled out a form, I'd like to get back error messages for every field on the form that is invalid. So I think validation messages should be carefully corralled and sent back in a format that is predictable and that can be consumed easily by the application.
I should be able to tell from the error or errors returned in the response whether the error or errors are authorization, request, or data validation errors.
Responses
Responses should come back in a format that is easy for the application to digest.
For a GET request, I might want to see some meta data about the collection returned, like stuff for pagination, the request parameters, error messages, and the collection itself of course.
For POST requests, I'd want to get back the created object. This is important because there might be some normalizations or auto-populated fields (like id) that I want to get back into my application. If there are errors, I'd want a collection of error messages.
For PUT requests, I'd also want to get back the updated object for the same reasons. If there are validation errors, I'd want a collection of error messages.
For DELETE requests, I'm not sure what I'd want other than an error if there is an error.
Documentation
I'd like to think that if error messages are done right that the api is 80% self-documenting. Documenting APIs really sounds like a chore. As a developer, looking up the documentation is a chore. It would be nice if, as a developer, and not some imaginary client that knows all things, the only thing I needed to start using an api is the root endpoint. From there I could discover resources, supported methods and parameters, and learn the api gradually as I build against it.
But if documentation is really necessary, maybe a "help" endpoint could live in the api so that I don't have to go somewhere else to learn how to use the api.
Side Effects
An api might have some kind of side effect, such as sending an email, or notifications when something happens.
Versioning
TODO this one is a monster. Makes my brain hurt.