独家优惠奖金 100% 高达 1 BTC + 180 免费旋转

What is REST?

Why this blog?

This blog highlights REST Best Practices intended for the developers who are interested in creating RESTful web services which provide high reliability and consistency across multiple service suites. We all know there are various resources on best practices for creating RESTful web services. However, it should also be known that many of the available resources are conflicting. Also, it’s likely not doable to refer, read and comprehend several books on this subject with a motto of implementing services “tomorrow”. This blog will enable you to quickly understand and grasp RESTful concepts with major concern on best practices and conventions.

In REST, the calls will be message based and dependent on HTTP standards to describe these messages. REST can be understood as a simple request/response mechanism, where each request returns a response. The following fig. will give you a better idea:

RESTful API’s, more popularly termed as REST API’s are the web services written using REST architecture.

REST is resource based. When we talk about REST, it indicates things or resources as opposed to actions in SOAP. In RESTful services noun represents the resources, for example, a person resource, a user resource. We use a HTTP verb (POST, PUT, GET, DELETE, etc.) to indicate what operation the REST API has to perform. Resources are identified by the URIs. It is possible to have multiple URIs pointing to same resource. RESTful API’s generally accept/return data in JSON or XML format.

Let’s quickly form an example with this basic knowledge before moving further. Suppose Sagar is a resource, there is a service to fetch contact information using the HTTP verb GET which will return the data like name, address, phone number, email address in JSON or XML form

1) Uniform Interface

2) Stateless

3) Cacheable

4) Client-Server

5) Layered System

6) Code on Demand

Let’s have a small review of each:

1) Uniform Interface:

It defines the interface between clients and servers. Uniform Interface simplifies and decouples the architecture. It enables each part to develop or evolve independently. Uniform interface describes the following four guidelines or principles:

2) tateless:

It is not required for the web server to remember the client’s state. The necessary state required to handle the request is included in the request itself, whether as part of URI, query-string parameters, body or headers.

3) Cacheable:

Clients can cache responses. Therefore Responses must explicitly or implicitly define themselves as cacheable or not which prevent the clients from reusing stale, old or inappropriate data in response to further requests.

4) Client-Server:

The uniform interface is responsible to separate the clients from the servers. Servers and clients can be developed independently. It conveys that the clients are not concerned with data storage which is internal to each server, which increases the portability of the client code. Servers are not concerned with the UI or user state, which makes the servers more scalable and simpler.

5) Layered System:

A client is unable to tell if it is connected directly to the end server or to an intermediary server. Intermediary servers may improve system scalability by providing shared caches and enabling load-balancing. Security policies can also be enforced through layers.

6) Code on Demand:

It is possible for the servers to extend or customize the functionality of a client on temporary basis by transferring logic to it that it can execute, for example: Java applets and client-side scripts like JavaScript.

HTTP Verbs/ Request Methods:

Clients specify their desired interaction method in the Request-Line part of an HTTP request message. Each HTTP method is bound to some specific, well-defined rules and meaning within the context of a REST API’s resource model.

The primary or most commonly used HTTP verbs or more properly called as methods are GET, PUT, POST and DELETE. These correspond to create, read, update, and delete operations respectively. OPTIONS and HEAD are the other verbs but are less frequently used.

GET:

The GET method is used to read or retrieve a representation of a resource. As GET method (along with HEAD) is used for READ only purposes hence they are considered safe as they do not change the data. GET (and HEAD) are considered as idempotent, i.e., making multiple identical requests end up having the same result as a single request.

Examples:

PUT:

We use PUT method mostly for update functionalities. Use this method for PUT-ing or updating data to a known resource URI along with the request body which contains the newly-updated representation of the original resource that we intend to change.

PUT method can also be used to create a resource in cases where resource ID is provided by the client instead of the server. But we must generally use POST to create new resources where the client defined ID is included in the body representation.

PUT is not a safe method, although it is idempotent.

Examples:

POST:

POST method is utilized to create new resources. This method is not safe nor idempotent.

Examples:

DELETE:

As the verb suggests, it is used to delete a resource identified by the URI.

Examples:

Response Status Codes:

Forty standard codes have been defined by HTTP to convey the results of a client’s request. These codes can be divided into following five categories:

CATEGORY

DESCRIPTION

1xx Informational

Indicates transfer protocol-level information.

2xx Success

Indicates that the client’s request was accepted/processed successfully.

3xx Redirection

Informs that the client needs to take some additional action to complete their request.

4xx Client Error

This category of error status codes defines the client’s error.

5xx Server Error

These error status codes indicate the server side errors.

All Items

Description

Let’s have a short and precise look over the success and error status codes.

HTTP response success codes:

CODE

NAME

MEANING

200

OK

Indicates a nonspecific success

201

Created

Indicates that a new resource has been created

202

Accepted

Indicates the start of an asynchronous action

204

No Content

Indicates that the body was left blank

301

Moved Permanently

Indicates that a new permanent URI has been assigned to the client’s requested resource.

303

See Other

Sent by controllers to return results that it considers optional.

304

Not Modified

Sent to preserve bandwidth (with conditional GET)

307

Temporary Redirect

Indicates that a temporary URI has been assigned to client’s requested resource.

HTTP response error codes:

CODE

NAME

MEANING

400

Bad Request

Indicates a non-specific client error.

401

Unauthorized

Indicates either client provided wrong/invalid credentials or missed to send them.

402

Forbidden

Indicates denied access to a protected resource.

404

Not Found

Sent when the client tried interacting with a URI which the REST API could not map to a resource.

405

Method Not Allowed

Sent when the client tried to communicate via an unsupported HTTP method.

406

Not Acceptable

Sent when the client tried to request data in an unsupportive type format.

409

Conflict

Indicates that the client attempted to violate resource state.

412

Precondition Failed

Informs the client that one of its pre-condition was not met.

415

Unsupported Media Type

Sent when the client submitted data which is of unsupported media type format.

500

Internal Server Error

Tells the client that API is having problems of its own.

Best Practices/Tips:

1) Use Noun instead of verbs:

Nouns are good and verbs are bad when it comes to rest standards. You can use the following easily understandable structure for every resource:

RESOURCE

GET

(READ)

POST

(CREATE)

PUT

(UPDATE)

DELETE

/customers

Returns a list of customers

Create a new customer

Bulk update customers

Delete all customers

/customers/1234

Return a specific customer

(405 — Method not allowed)

Updates a specific customer

Delete a specific customer

Bad practice is to use verbs like:

Nouns are good and verbs are bad when it comes to rest standards. You can use the following easily understandable structure for every resource:

2) GET method and query parameters should never be used to update or alter the state:

Never use GET to alter or state changes. Use GET, POST or DELETEto alter the state.

3) Use plural forms of noun:

Keep the resource naming simple by following plural forms of nouns. Even though you might think that it is grammatically incorrect, but the best standard for REST practices is to use plurals.

4) Use sub-resources for relations:

If you have some resource which is related to another resource then it is implied to use sub-resources:

5) Use HTTP headers for serialization formats:

The client side and server side both should know and use the format that is being used for communication. This format has to be specified in the HTTP-header.

6) Error handling and using status codes:

It is very difficult to work under situations where proper error handling is ignored. Just returning of HTTP 500 with a stack trace log is not enough.. We need to make proper usage of the HTTP status codes that have been covered in the earlier part.

7) Include scope for paging, sorting, filtering and field selection:

Pagination:

Use limit and offset for pagination. It is not only flexible for the user but also common in the leading databases.

Sorting:

Ascending and descending sorting should be provided. Also, allow sorting over multiple fields.

Filtering:

We can make use of unique query parameter for all fields or may be use a query language for filtering purpose.

Field Selection:

It is a very common practice that mobile clients wish to display only few attributes. They don’t want to display or use all the attributes of a resource. Thus an API should have the ability that allow the mobile clients to choose the returned fields. This helps to save the mobile battery, reduce network traffic and speeds up the API usage.

GET /customers?fields=name,age,contact number

8) Documentation:

One last suggestion is to maintain an update API document. This document should be shared and accessible to all concerned people. Most client-side developers should check the API document before starting integration of web services. The doc should cover all necessary information like request URL, response body format, headers etc. For every API try to cover with an example of request body and response bodies with all the alternative responses including error and success.

Conclusion:

I hope the above content is easily understandable and lets you get started with developing REST API with some good level standards and consistency in your coding style. Just follow these REST best practices and you’re all set.

Full Stack Developer At MindBowser Info Solutions

Add a comment

What is your view?

Send

Related posts:

Aiur Bounty Program invites the crypto community to push for Open Science!

At Iris.ai we often get questions about the technology behind Project Aiur. We love to talk about the fascinating advances in AI and blockchain and how we envision to apply them for building the…

Why Choose To Build Patios For Your Homes

Heaven is a house with a patio. A patio is a place where you can read a book or just relax, listen to the chirping birds, sip your lemonade, enjoy the beautiful weather and even watch the sunset with…