1. Better RESTFul API – Best Practices
SolarWinds
Better RESTFul API – Best Practices

2. 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

3. 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

4. How REST Api should be? Heterogeny (language, platform) Stateless
Simple
Intuitive
Consistent
Reliable
Efficient
Friendly to work with

5. https://cp.solarwinds.com/pages/viewpage.action?pageId=92131573
Coding
Prepare environment

6. 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.

7. 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

8. Use plural nouns

9. Don’t expose Get (All)
Allow
paging
sorting
filtering
field selection

10. Coding
Proper implementation of GET

11. Use HTTP verb status code

12. 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.

13. Coding
Return proper HTTP Code

14. 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

15. Coding
Proper patch implementation

16. 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

17. Coding
Sub-resources

18. 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

19. 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 )

20. Write /expose documentation