reading notes for code fellows
This is important to what we are currently doing because we need to know what all of the different things we can do with APIs are and how to structure them.
A well designed API should aim to support platform independance and service evolution. REST (Representational State Transfer) was proposed by Roy Fielding as an architechtural approach based on hypermedia to designing web services. REST is not tied to HTTP, but it is most commonly used with HTTP as the protocol.
A primary advantage of REST is that it uses open standards, meaning it can be used with any language that understands HTTP. Some of the main design principles of REST using HTTP are
The API design should be focused on the entities that it esposes, based around the resources themselves and not the operations. A resource doesn’t have to be based on a single item, but they shouldn’t model a database structure. Entities are often grouped into collections, which are separate from the items within them and should have a separate URL. URLs should have a consistent naming convention and usually should be plural when referencing collections and organized hierarchically. Generally URLs should not be more complicated than three layers deep. All requests also impose a load on the server, so you should avoiding a number of small resources with your API. Also avoid introducing dependancies between your API and data sources.
The HTTP methods most used by REST are
Within the HTTP protocol, formats are specified through MIME (media) types. For non-binary data, most web APIs support JSON or XML. Sometimes one of the HTTP methods may tay some time to complete, and in this case you may want to run asynchronous code and return the code 202(accepted) to indicate the request was accepted but is currently processing. If this is the case, you should return an endpoint that can monitor the status of the request for the client and optionally cancel it.
When retrieving data from an API that can be filtered, it should be done on the side of the API if possible, to avoid inefficiency on the client side and on the server. You can also set a limit on number of items that can be returned. In the case of large binary fields, you can enable them to be retrieved in chunks to improve response time.
You should use HATEOAS (Hypertext as the Engine of Application State) to structure your GET request returns to be necessary information related to the requested object.
If you use versioning on an API, old clients can continue on as they were without needing to update while new clients can take advantage of new features and resources, though no versioning is more common.
I want to know a bit more about implementing the different types of versioning.