cool hit counter RESTAPI Design and Development Best Practices_Intefrankly

RESTAPI Design and Development Best Practices

21CTO Community Read: In this article, my goal is to explain the REST API to you in as much detail as possible, including the theoretical and development parts. so that everyone can clearly understand when to use it and how to use it, including what its essence is. Whether you develop your own API or use a third-party API, it will be much smoother.

Companies like Alibaba,Baidu,Tecent,Toutiao, Facebook,Google,Amazon etc. have open RESTful APIs or openings that we can apply to access, get and even write data.

Everything has to ask why. Why do I need a REST API? Why is REST so popular?

There are, of course, many ways to deliver a message. such as Socket, REST, WebService, HTTP, etc.

What's the difference between REST and HTTP?

REST is flexible and compatible with the HTTP protocol. It is an architectural style, not a standard, with which to provide various services that can be implemented in various programming languages.

In this post, our goal is to get a clear understanding of REST together, knowing when to use it and how to use it, and the nature of REST.

We will go through some basics and definitions, including best practices for REST APIs, that can enable you guys to implement REST APIs in any development language.

It is recommended that you have a basic understanding of the HTTP protocol, or a partial understanding that will allow you to fully digest this section.

The Nature of REST

REST - Representational State Transfer is an architectural style created by Dr. Roy Field, who described the architectural style and web-based software architecture design in his paper at UC Irvine, and developed using HTTP 1.1.

We use REST as a way to communicate between different computer systems on the Internet.

REST binding HTTP

Not according to the REST definition. Although one can use a number of other REST application protocols, HTTP remains the undisputed dominant application protocol when it comes to REST implementations.

The meaning of RESTful API

RESTful has some of the following features.

1、Client/server architecture: The complete service consists of a front-end "client" and a back-end "server" of the whole system.

2、stateless: Servers in different requesting No state is saved in between。 The state of the session is entirely the responsibility of the client。 depending onREST Definition of: allREST The interactions are all stateless, that is say, everyone requesting Both contain connector understanding requesting All the information required, without being subject to any prior possibility of requesting effects。

3. Cacheable: the client should be able to store the response in the cache for better performance.

The RESTful API follows these rules above and uses HTTP methods to manipulate the services of the resource set.

Why you need to use Restful API

Because they provide a simple, flexible and scalable way to develop distributed applications for Web communication.

We probably have a lot of REST APIs. If the business is broad enough, the services that need to be open can become complex.

Developers need some pragmatism to make good apps and services.

Theory is important for cognitive understanding, but it is the implementation of the theory that is the test for distinguishing differences in superior and inferior applications. For this reason, we have to work smart, but must remember that the end user is the first priority and the highest value.

We know the point, make the API do powerful easy and make the user's job easier too .

Abstract and business-specific APIs

When developing software, we will often use object-oriented abstraction and polymorphism to develop applications. This maximizes the reuse of code.

So, is this how we should develop REST APIs as well?

It's a different story when it comes to developing APIs; with REST APIs, concrete is better than abstract. That is, it's better to accomplish the actual function. Let's look at some examples.

There are two api versions.






Which description would be clearer to you as a developer, and which API would you rather use? I'll go with the second one.

URI format, using nouns rather than verbs

Here's another best practice for API development. How do we format your nodes? If you use the encoded approach to naming URI nodes, it will be the following.






I think you already understand that this will have many URL nodes, each doing only one thing.

We're going to have a more systematic naming to streamline and sort out this mess above. Start by describing the resource as a noun and replace the HTTP method with a verb. So we get the following result.

GET /blogpsots - Get all blogs

GET /blogposts/12 - Get the blog with ID 12

POST /blogposts - add a new blog, return error message

DELETE /blogposts/12 - Delete the blog with ID 12

GET /author/3/blogposts - Get all the blogs of the author with ID 3

Thus, a cleaner, more precise API emerges. For the user who uses it, he will be clear right away. Of course, you can use the singular form instead of the plural form, which makes it seem like a neater resource name, it's up to you depending on your preference.

error handling

This phase is another important aspect of API development. There are several good ways to deal with errors.

Let's see how some advanced development dogs do it.



Response: Status code 400

{"errors":[{"code":215,"message":"Bad Authentication data."}]}

Twitter gives us the status code and error code, along with a short description.



Response: Status code 400


"error": {

"message": "An active access token must be used to query information about the current user.",

"type": "OAuthException",

"code": 2500,

"fbtrace_id": "DzkTMkgIA7V"



Facebook gives enough to give you a more specific error message.



Response: Status code 404


The requested resource /2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234 was not found


Twilio gives us an XML ringing on the format and the ability to chain to documents where you can find the details of the error.

We have seen some differences in the way different developers provide But these open platforms provide specific error messages that don't simply tell users that they're unavailable, leaving them wondering what happened and leaving them searching aimlessly in search engines only to waste time.

Return Status Code

When designing a REST API, it is necessary to use HTTP status code to communicate with the API.

As you can imagine, HTTP has a lot of ready-made status codes that describe some of the possible responses.

But how much should we use? Should we have strict state codes for every situation?

With over 70 states of HTTP status codes, do you know the core of them? API users whether they will use them or not to avoid making people look them up again. Most of us are familiar with the following status codes.

200 OK

400 Bad Request

500 Internal Server Error

Let's start with these three points to cover most of the functionality of the REST API step by step.

Other common status codes.

201 Created

204 No Content

401 Unauthorized

403 Forbidden

404 Not Found

Functions can be used to help users find out the results quickly. If it is felt that the status code is not sufficient to display descriptive content in error handling, then some type of message should be included. Then the code and descriptive information is used to help API users.


REST API security relies on standard HTTP mechanisms such as basic authentication or digest authentication .

Every request should be made over HTTPS .

raiseREST API of security Sex has many tricks., But sinceREST The stateless nature of, Please be very careful when implementing them。 For example, the last one requesting The status of the, The client should store and verify the state。

additionally, Using Timestamps and Records requesting It helps us a lot too.。

1、Mozilla opens source code for read later app Pocket
2、Two years after graduation he did the right thing and made his son a rich kid
3、EOSAlliance Foundation Outlook
4、Blockchain bubble or opportunity
5、Daily Security Update Push

    已推荐到看一看 和朋友分享想法
    最多200字,当前共 发送