RESTful API Design Best Practices

Web APIs have become more and more popular in recent years, and the simplicity of API design has become particularly important in multi-backend system interaction applications. In general, RESTful APIs are used as our Web API. This article describes some of the best practices for designing simple RESTful APIs.

A noun used instead of a verb

Using nouns to define interfaces, verbs should not be used:

/getallresources

/createnewresource

/deleteallresources

Two, GET methods and query parameters can not change the resource state

If you want to change the state of a resource, use PUT, POST, and DELETE. The following is an error using the GET method to modify the user's state:

Get/users/711?activate or

Get/users/711/activate

Iii. use of plural nouns

Do not confuse nouns with singular plural. Keep it simple and define all resources with plural nouns only.

/cars instead of/car

/users instead of/user

/products instead of/product

/settings instead of/setting

Use sub-resources to express relationships between resources

get/cars/711/drivers/returns the list of all driver for car No. No. 711

GET/CARS/711/DRIVERS/4 returns number 4th of Car No. No. 711 Driver

Iv. using the HTTP header to serialize the format

Both the client and the server need to know the communication format between each other. These formats can be defined in the HTTP header:

• Content-type: Defines the request format

• Accept: Defines a list of received formats

Using HATEOAS constraints

HATEOAS (hypermedia as the engine of application state) is the most complex constraint in the rest architecture style and is at the heart of building a mature rest service. It is important to break down the strict contract between the client and the server, which makes the client more intelligent and adaptive, and the REST service itself becomes easier to evolve and update. Before introducing HATEOAS, let's introduce the REST maturity Model proposed by Richardson. The model divides the REST service into 4 levels of maturity:

• The first (level 0) Web service only uses HTTP as a transport, and is actually a specific form of a remote method call (RPC). Both SOAP and Xml-rpc belong to this class.

• The second (Level 1) Web service introduces the concept of resources. Each resource has a corresponding identifier and expression.

• The third level of the Web service, which uses different HTTP methods for different operations, uses HTTP status codes to represent different results. such as the HTTP GET method to get the resource, the HTTP Delete method to delete the resource.

• The fourth tier (Level 3) Web service uses HATEOAS. The link information is included in the expression of the resource. The client can discover the actions that can be performed based on the link.

As you can see from the rest maturity model above, the rest service using HATEOAS is the most mature and recommended practice. For REST services that do not use HATEOAS, the implementation of the client and server is tightly coupled. The client needs to understand the exposed resources and the corresponding actions according to the relevant documentation provided by the server. When the server changes, such as modifying the URI of the resource, the client also needs to make corresponding modifications. With HATEOAS's REST service, clients can intelligently discover what they can do with the expression of the resources provided by the server. When the server changes, the client does not need to make modifications because the URI and other information of the resource is dynamically discovered.

Here is an example of a HATEOAS:

{

"id": 711,

"Manufacturer": "BMW",

"Model": "X5",

"Seats": 5,

"Drivers": [

{

"id": "23",

"Name": "Stefan jauker",

"Links": [

{

"rel": "Self",

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

}

]

}

]

}

Provides filtering, sorting, field selection, paging

Filter:

Get/cars?color=red

get/cars?seats<=2

Sort:

Get/cars?sort=-manufactorer,+model

Field selection:

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

Paging:

Get/cars?offset=10&limit=5

API Versioning

The version number uses a simple ordinal number, and avoids dot symbols, such as 2.5. The correct usage is as follows:

/blog/api/v1

Full use of HTTP status codes to handle errors

The HTTP status code is a 3-bit numeric code that represents the HTTP response status of the Web server. It is defined by the RFC 2616 specification and is extended by specifications such as RFC 2518, RFC 2817, RFC 2295, RFC 2774, RFC 4918, and so on.

When designing an API to handle errors, you should use HTTP status codes instead of simply throwing "500–internal Server error" (Internal server errors).

All exceptions should have a wrong payload as the map, here is an example:

{

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

}

]

}

RESTful API Design Best Practices