We have a client-server Internet protocol, HTTP, which assigns very general meanings to different kinds of requests: GET, POST, PUT,
and so on.
We have the idea of hypermedia, which allows the server to tell the client which HTTP requests it might want to make next. This frees the client from having to know the shape of the API ahead of time.
We have the idea of application semantics, which extend hypermedia controls with information about what specifically will happen, to application or resource state, if the client makes a certain HTTP request.
And finally we have a whole lot of standards for building APIs (Html, HAL, Siren, Collection+JSON, ODATA, Atom-Pub, RSS etc)
So how do we make sense in all of the above before defining our API.
Here are some useful rules defined by Leonard Richardson:
1. Is there a domain-specific standard for your problem? If so, use it. Document any
2. Does your problem fit the collection pattern? If so, adopt one of the collection
standards. Define an application-specific vocabulary and document it.
3. If neither of those is true, choose a general hypermedia format. Break down your
application into its state transitions. Document those state transitions
4. At this point, you have your protocol semantics nailed down. The application semantics are all that remain.
Are there existing microdata items or microformats that cover your problem domain? If so, use them.
Otherwise, define an application specific vocabulary and document it.
More on this can be found in Leonard Richardson book : RESTful Web APIs which I strongly recommend.