10 best practices for good design of restful APIs

The Web API has become an important topic in recent years, and a clean API design is important for back-end systems.

Usually we use restful design for the Web API, the rest concept separates the API structure and logical resources, and uses HTTP method get, DELETE, POST and put to manipulate resources.

Here are 10 best practices for RESTful Web APIs that can provide you with a good API design style.

1. Use nouns rather than verbs

Resource Resources	GET Read	POST Create	PUT Modify	PATCH Partial modifications	DELETE
/cars	Back to Cars Collection	Create a new resource	Batch Update cars	Bulk update of Cars part content	Remove All cars
/cars/711	Returns a specific car	This method does not allow (405)	To update a specified resource	Update partial content of a specified resource	Good at assigning resources

Do not use:

/getallcars
/createnewcar
/deleteallredcars

2.Get methods and query parameters should not involve state changes

Use the PUT, POST , and DELETE methods instead of the get method to change the state, and do not use get for state changes:

Get/users/711?activate
Get/users/711/activate

3. Using plural nouns

Do not confuse noun singular and plural, in order to keep it simple, use complex numbers only for all resources.

/cars, not/car.
/users, not/user.
/products, not/product.
/settings and Deploy/setting

4. Using child resources to express relationships

If a resource has a relationship with another resource, use a child resource:

get/cars/711/drivers/returns all drivers for car 711
GET/CARS/711/DRIVERS/4 back to Car # 4th driver 711

5. Declaring serialization formats with HTTP headers

On both the client and server side, both sides need to know the format of the communication, the format specified in Http-header

Content-type Defining request formats
Accept defines a series of acceptable response formats

6. Use HATEOAS

HYpermedia as The Engine oF application sTate Hypermedia as the engine of application status, hypertext links can create better text browsing:

{

"id": 711,

"Manufacturer": "BMW",

"Model": "X5",

"Seats": 5,

"Drivers": [

{

"id": "23",

"Name": "Stefan jauker",

"Links": [

{

"rel": "Self",

"href": "/API/V1/DRIVERS/23"

}

]

}

]

}

Note that the href points to the next URL

7. Provide the collection with filtering sorting options and paging functions

Filtering filter :

Filter by using unique query parameters:

Get/cars?color=red back to the red cars
get/cars?seats<=2 returns a cars collection of less than two seats

sorting Sort by:

Allow sorting on multiple fields

Get/cars?sort=-manufactorer,+model

This is the car collection that is returned according to the producer descending order and the model ascending

Field selection

The mobile side can display some of these fields, they actually do not need all the fields of a resource, give the API consumer a choice field ability, this will reduce network traffic, improve API usability.

Get/cars?fields=manufacturer,model,id,color

Paging Sub-page

Use limit and offset. Implement paging, default limit=20 and offset=0;

Get/cars?offset=10&limit=5

To send the total to the client, use the custom HTTP header: X-total-count.

Link to next or previous page in the HTTP header, follow the link rules:

Link:

8. Versioning your API

Make the API version mandatory, do not publish a version-free API, use simple numbers, avoid decimal points such as 2.5.

Usually used behind a URL? V

/blog/api/v1

9. Handling errors using HTTP status codes

If your API is not error-handling is difficult, just return 500 and the error stack is not necessarily useful

HTTP status Code provides 70 errors, we only need to use 10 or so:

200–ok– everything's fine.
201–ok– a new resource has been created successfully
204–ok– resources have been successful at

304–not modified– client uses cached data

400–bad request– request is invalid and requires additional details to explain such as "JSON is invalid"
401–unauthorized– request requires user authentication
The 403–forbidden– server has understood the request, but denial of service or access to such a request is not allowed.
404–not found– did not find the resource
422–unprocessable entity– is only used when the server cannot process the entity, the image cannot be formatted, or the critical field is lost.

500–internal Server ERROR–API Developers should avoid this error.

Use verbose error wrapping error:

{

"Errors": [

{

"Usermessage": "Sorry, the requested resource does not exist",

"Internalmessage": "No car found in the database",

"Code": 34,

"More Info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"

}

]

}

10. Allow overriding of HTTP methods

Some proxies support only the POST and get methods, in order to support the RESTful API with these limited methods, a way to overwrite the HTTP original method is needed.

Use the custom HTTP header x-http-method-override to overwrite the Post method.

Transferred from: http://www.jdon.com/soa/10-best-practices-for-better-restful-api.html

10 best practices for good design of restful APIs