Better RESTFul API – Best Practices SolarWinds Better RESTFul API – Best Practices
REST Architectural Style (not a protocol or design pattern) way of thinking & designing applications Resource oriented Separate API structure into logical resource x not a way to call methods over a network without the overhead of SOAP and WSDL
RESTful API An API is a developer's UI - just like any UI, it's important to ensure the user's experience is thought out carefully It represents a contract between you and those who Consume data Good desing is hard The easier your API is to consume, the more people that will consume it
How REST Api should be? Heterogeny (language, platform) Stateless Simple Intuitive Consistent Reliable Efficient Friendly to work with
https://cp.solarwinds.com/pages/viewpage.action?pageId=92131573 Coding Prepare environment https://cp.solarwinds.com/pages/viewpage.action?pageId=92131573
Use Verbs GET (SELECT): Retrieve a specific Resource from the Server, or a listing of Resources. POST (CREATE): Create a new Resource on the Server. PUT (UPDATE): Update a Resource on the Server, providing the entire Resource. PATCH (UPDATE): Update a Resource on the Server, providing only changed attributes. DELETE (DELETE): Remove a Resource from the Server. Here are two lesser known HTTP verbs: HEAD – Retrieve meta data about a Resource, such as a hash of the data or when it was last updated. OPTIONS – Retrieve information about what the Consumer is allowed to do with the Resource.
Endpoints - Use nouns but no verbs Never include actions / verbs as URL segments. Use nouns Do not use verbs: Resource GET read POST create PUT update DELETE /cars Returns a list of cars Create a new ticket Bulk update of cars Delete all cars /cars/711 Returns a specific car Method not allowed (405) Updates a specific ticket Deletes a specific ticket
Use plural nouns
Don’t expose Get (All) Allow paging sorting filtering field selection
Coding Proper implementation of GET
Use HTTP verb status code
Use HTTP status codes 200 – OK – Eyerything is working 201 – OK – New resource has been created 204 – OK – The resource was successfully deleted 304 – Not Modified – The client can use cached data 400 – Bad Request – The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. „The JSON is not valid“ 401 – Unauthorized – The request requires an user authentication 403 – Forbidden – The server understood the request, but is refusing it or the access is not allowed. 404 – Not found – There is no resource behind the URI. 422 – Unprocessable Entity – Should be used if the server cannot process the enitity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload. 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.
Coding Return proper HTTP Code
Implement properly Patch (partial update) JSON Patch is a format (identified by the media type “application/json-patch+json”) for expressing a sequence of operations to apply to a target JSON document Array of objects Each represents a single Operation (specific task to perform https://www.janaks.com.np/implementing-jsonpatch-in-aspnet-core/
Coding Proper patch implementation
Use sub-resources We would like to get sub collection of a resource api/books/{bookid}/pictures We need to create additional endpoint Recomended to create separate controller
Coding Sub-resources
RPC-Style Calls Execusion based rather than resource based It’s not about data it’s about action /books/1/salesreport Let’s be pragmatic (sometimes we need somthing like this) Should be stateless Should be exceptional behaviour
Versioning Software evolves, API must be versioned Users/Customers rely on the API not changing But Requirements will change Support both new and old users Api Versioning != project versioning (Api Versioning is harder )
Write /expose documentation https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger