什么是REST API和REST-ful API(What are rest APIs and rest ful APIs)

REST api也叫RESTful api。是一种设计风格或者说是一种设计规范,REST是 Representational State Transfer的缩写。翻译过来是 具体的(表述性)状态转移。RESTful ap翻译成中文是 完全的状态转移API。通俗的讲就是’通过语义化的方式请求资源URL,并根据返回的语义来判断这次操作失误返回类型和效果’。语义化:需要做什么动作的时候,可以把动作通过头信息里的代表动作的method语义来告诉服务端

RESTful api拥有清楚简短的URL,可读性非常强

在1993年http 0.9时,只有get请求,常常做什么具体操作时都是通过url体现,比如对用户表增删改查,分别对应api/addUser,api/updateUser,api/delUser,api/listUser来操作加上返回的状态属性…这样一个user对象的操作就会产生成很多条URL,这是一般api的写法。RESTful api的出现大大解决了这类问题,即操作一个user对象,只需要一个api[api/user]去操作State(User的状态,资源)即可,把其它剩下的都放在Representational中。除了请求的内容外的其它都可以理解为Representational。

REST,又称为 Representational State Transfer,全名为 Resource Representational State Transfer,中文可以翻成 具象状态传输Resource : 资源Representational : 像是 JSON,XML,YAML 等等……State Transfer : 状态传输。透过 HTTP 动词实现 ( GET,POST,PUT,DELETE),状态可以定义成 Resource 的状态,类似资料库中 CRUD 操作后的结果。以上看不懂没关系,略懂即可,我知道很难懂

先给大家一个观念,RESTful 是一种设计风格,或者说是一种设计规范为什麽我们要使用 RESTful API ? 用一般的 API 不行吗?一般的 API 可能长得像这样 /api/get_file/ (得到档案) /api/upload_file/ (新增档案) /api/upload_file/ (更新档案) /api/upload_file/ (删除档案)

RESTful API 则长得像这样 /api/files/ ( GET -> 得到档案 ) /api/files/ ( POST -> 新增档案 ) /api/files/ ( PUT -> 更新档案) /api/files/ ( DELETE -> 删除档案 )

温馨小提醒 不知道大家有没有注意到我用复数,实务上用复数比较多。从上面的比较可以发现,使用 RESTful API 我们只需要一个接口就可以完成 ,并且我们透过 HTTP 不同的 method 达到相对应的功能。RESTful API 让我们以很优雅的方式显示 Resource ( 资源 ),Resource ( 资源 ) 是由 URI 来指定,( URI 是什麽,这边不详细介绍,就麻烦大家 Google,可以先简单想为 URL 是一种 URI 就好 )对 Resource ( 资源 ) 的操作,包含取得、新增、修改和删除资源,这些操作刚好对应 HTTP 协定提供的 GET、POST、PUT 和 DELETE 方法 。

RESTful API 拥有清楚又简短的 URI,可读性非常强,举个例子- GET /api/files/ 得到所有档案- GET /api/files/1 得到档案 ID 为 1 的档案- POST /api/files/ 新增一个档案- PUT /api/files/1 更新 ID 为 1 的档案- PATCH /api/files/1 更新 ID 为 1 的部分档案内容- DELETE /api/files/1 删除 ID 为 1 的档案

上面做的事情就是 CRUD,那什麽是 CRUD ,也就是Create( 新增 )、 Rea诶( 读取 )、 Up诶ate( 更新 )、 Delete(删除)温馨小提醒 特别来说明一下 PUT 和 PATCH,PUT 比较正确的定义是 Replace ( Create or Update ),例如 PUT /api/files/1/ 的意思是替换 /api/files/1/,假如已经存在就替换,如果没有也就新增,当然,新增的时候,必须包含必要的资料。因为上面这个原因,大家会看到有时候使用 PUT 新增,也因为这个有点怪的行为,所以又多了 PATCH 这个方法,可以用来做部分更新 ( Partial Update )。或是我想搜寻档案名称为 hello 的档案,RESTful API 可能为GET /api/files/search?key=hello

看到这边,可以把 RESTful 想成是一种建立在 HTTP 协定之上的设计模式,充分的利用出 HTTP 协定的特定,使用 URI 来表示资源,用各个不同的 HTTP 动词(GET、POST、PUT 和 DELETE 方法 )来表示对资源的各种行为,这样做的好处就是资源和操作分离,让对资源的管理有更好的规范以及前端(串接 API 或使用 API 的人)可以很快速的了解你的API ,省去很多不必要的沟通,如果熟悉 HTTP Method 的开发者,甚至可以不用看 API文件就开始串接资料,当然,如果是更复杂的 API ,可能还是需要搭配文件,文件的撰写可参考我之前写的aglio_tutorial(https://github.com/twtrubiks/aglio_tutorial) 以及 诶jango_rest_framework_swagger_tutorial(https://github.com/twtrubiks/django_rest_framework_swagger_tutorial)这样你现在是不是在想,RESTful 太神啦

Safe and Method Idempotent

GET 方法是安全方法,也就是不会对 Server 有修改,你只是读取而已,并不像 POST,PUT,DELETE,PATCH 这类的会修改资料。

Method Idempotent ( 幂等方法 ),

他是什麽呢? 简单解释,假设不考虑错误其他因素,若我们请求多次和单次结果( API 的 response )是一样的,就是 Method Idempotent。像是 GET 就是 Method Idempotent,因为不管请求几次,结果都是相同的;反之,像是 POST 就不是 Method Idempotent ,原因是当我们发起第两次 POST 时,就会又新增一笔资料。

安全方法和 Method Idempotent 可参考下面的表格HTTP Method Idempotent SafeOPTIONS yes yesGET yes yesHEAD yes yesPUT yes noPOST no noDELETE yes noPATCH no no相信从上面这个表格,大家应该蛮好理解的,比较不好理解的可能就是,为什麽 PATCH 不是 Method Idempotent,不是很好解释 我在这裡简单解释,PATCH 请求是会执行某个程序的,如果重複请求,程序则可能多次执行,对 Server 端的资源就可能会造成额外的影响,所以他不是 Method Idempotent。

如果大家想要更深入理解,麻烦大家 google

RESTful API 缺点记住,世界上没有完美的东西,一定有他的缺点,RESTful 很方便没错,但只要用户了解了您的网站 URL 结构,就会开始产生 安全性 的问题思考一个问题,一个用户任意对你的 Database ( 资料库 ) 操作 CRUD 是一件很可怕的事情 再思考一个问题,假设我们得到一个使用者的 URL 是这样 /api/uesrs/1/,一般来说使用者只能存取自己的用户资料,并不能查看别的用户资料。否则,有心人可以尝试从 /api/uesrs/1/ 开始 try 到 /api/uesrs/100/ 得到其他的用户资料。这是比较基本了问题,通常我们会先去验证这个使用者的身份,再来决定是否有权限可以存取用户资料,所以我们一定要再处理对用户进行身份

验证和授权(可参考之前在 诶jango-rest-framework-tutorial (https://github.com/twtrubiks/django-rest-framework-tutorial#%E6%8E%88%E6%AC%8A-authentications-)里介绍的授权),然后使用 HTTPS。

再谈谈一个问题,现在很多都是前后端分离,通常我们会为了方便以 JSON 作为传送的格式,但是有时候可能会不小心把一些敏感的资讯送到前端,这样就可能会导致资料外泄,或是有心人透过这些资讯,去得到别人的资料以及有意思的讯息。所以当你在设计 API 时,一定要想想这些资讯泄漏了会不会有什麽影响,如果有,可能资料需要再被加密之类的。接著思考这个问题,有时候我们为了取得资料,可能必须呼叫多次 API 才可以得到完整的资讯,举个例子,想要取得文章与作者的资讯,会先呼叫 GET/articles/{id}/ 取得文章的作者后,再呼叫GET/uesrs/{name}/ 去取得作者的资讯,像这个情况,我就会觉得或许可以小小的动个手脚,不需要非常严格的遵守它,另外像是 GraphQL 就能够通过一次查询得到所有需要的资料 ( 这个以后有机会我再来介绍 )。也因为上面这个原因,有可能我们的 API 会不小心设计成需要呼叫某个 API 之后,才能呼叫另一个 API这种有关连性的设计 ( 导致系统越来越乱 ) 所以这些都要注意再来,假设今天要设计一个 批量 删除的 API,应该要怎麽规划会比较好呢全都放在 URI 上 那如果它超出限制的长度呢最后一个问题是实际面的问题,很多时候,我们的业务逻辑非常复杂,会导致如果要很严格的遵守RESTful API 的规则,就不是那么的好用,所以,有时候还是可以在 RESTful API 做一些修改,不一定要那麽死死得遵守他的规则 。

状态码操作 API 的用户,可以透过 HTTP 状态码了解一定的意思HTTP status co诶e 的常用情境如下 ( 通常,但不是绝对 )200 OK 用于请求成功 。GET 档案成功,PUT, PATCH 更新成功201 Create诶 用于请求 POST 成功建立资料。204 No Content 用于请求 DELETE 成功。400 Bad Request 用于请求 API 参数不正确的情况,例如传入的 JSON 格式错误。401 Unauthorized 用于表示请求的 API 缺少身份验证资讯。403 Forbidden 用于表示该资源不允许特定用户访问。404 Not Found 用于表示请求一个不存在的资源。更多详细的可以参考 HTTP Status Codes

如果你的 API 比较复杂,还是要有文件记录你的 error code 。

依据不同的 API 操作,定义适合的 HTTP 状态码和必要的错误资讯

( 回传一个 JSON 并且包含 error 属性,error 这个属性记录错误讯息)。

结论这次和大家简单介绍了 RESTful API 的概念,基本上,还有很多可以研究,像是避免API 被攻击,可以考虑启用 API 调用速率限制( Rate limiting),又或是 HTTP Cache的机制,最后,欢迎大家进入 RESTful 的世界

————————

The rest API is also called restful API. Rest is a design style or a design specification. Rest is the abbreviation of representative state transfer. Translated as a concrete (expressive) state transition. Restful AP translated into Chinese is a complete state transition API. Generally speaking, it means’ request the resource URL in a semantic way, and judge the return type and effect of this operation error according to the returned semantics’. Semantic: when you need to do any action, you can tell the server the action through the method semantics representing the action in the header information

The restful API has a clear and short URL, which is very readable

At http 0.9 in 1993, there was only get request, and the specific operations were often reflected through the URL. For example, adding, deleting, modifying and querying the user table, corresponding to API / addUser, API / updateuser, API / deluser and API / listuser respectively, plus the returned status attribute The operation of such a user object will generate many URLs, which is the writing method of the general API. The emergence of restful API has greatly solved this kind of problem, that is, to operate a user object, you only need an API [API / user] to operate the state (user’s state and resources), and put the rest in representational. Everything except the requested content can be understood as representative.

Rest, also known as representative state transfer, its full name is resource representative state transfer, which can be translated into concrete state transfer in Chinese. Resource: resource representative: such as JSON, XML, yaml, etc State transfer: state transfer. Through HTTP verbs (get, post, put, delete), the status can be defined as the status of the resource, similar to the result of crud operation in the database. It doesn’t matter if you don’t understand the above. Just understand it a little. I know it’s difficult to understand

First of all, let’s give you an idea. Restful is a design style, or a design specification. Why do we use restful API? Can’t you use a general API? General APIs may look like this / api/get_ file/ (get files) / api/upload_ File / (new file) / api/upload_ File / (update file) / api/upload_ file/ (delete file)

Restful APIs look like this / API / files / (get – & gt; get files) / API / files / (post – & gt; add file) / API / files / (put – & gt; update files) / API / files / (delete – & gt; delete files)

I don’t know if you have noticed that I use the plural. In practice, I use the plural more. From the above comparison, it can be found that using restful API, we only need one interface, and we can achieve the corresponding functions through different methods of HTTP. The restful API allows us to display resources in a very elegant way. Resources are specified by URIs. (what URIs are, we won’t introduce them in detail here, so we’ll trouble Google. We can simply think that URLs are URIs first.) the operations on resources include obtaining, adding, modifying and deleting resources. These operations just correspond to the get, post, put and delete methods provided by the HTTP protocol.

Restful API has a clear and short URI, which is very readable. For example – get / API / files / get all files – get / API / files / 1 get files with file ID 1 – post / API / files / add a file – put / API / files / 1 update files with ID 1 – patch / API / files / 1 update some file contents with ID 1 – delete / API / files / 1 delete files with ID 1

The above is crud. What is crud? That is, create, read, update and delete. In particular, put and patch are correctly defined as replace (create or update). For example, put / API / files / 1 / means replace / API / files / 1 /. If it already exists, replace it. If not, add it. Of course, Necessary data must be included when adding new ones. For the above reasons, you can see that sometimes put is used to add, and because of this strange behavior, patch is added, which can be used for partial update. Or I want to search for a file named hello. The restful API may be get / API / files / search? key=hello

Here, we can think of restful as a design pattern based on the HTTP protocol. We can make full use of the specific of the HTTP protocol, use URIs to represent resources, and use different HTTP verbs (get, post, put and delete methods) to represent various behaviors to resources. The advantage of this is the separation of resources and operations, Make the resource management more standardized and the front end (people who connect or use APIs in series) can quickly understand your API, eliminating a lot of unnecessary communication. If developers who are familiar with HTTP method can even start connecting materials without looking at the API file. Of course, if it is a more complex API, it may still need to match the file. For the writing of the file, please refer to Aglio I wrote before_ tutorial( https://github.com/twtrubiks/aglio_tutorial )And Jango_ rest_ framework_ swagger_ tutorial( https://github.com/twtrubiks/django_rest_framework_swagger_tutorial )So are you thinking, restful is so amazing

Safe and Method Idempotent

The get method is a secure method, that is, it will not modify the server. You just read it. Unlike post, put, delete and patch, it will modify data.

Method idempotent,

What is he? For a simple explanation, assuming that the error and other factors are not considered, if we request multiple times and the single result (API response) is the same, it is method idempotent. For example, get is method idempotent, because no matter how many times the request is made, the result is the same; On the contrary, for example, post is not method idempotent, because when we launch the second post, another data will be added.

For the security method and method idempotent, please refer to the following table http Method Idempotent SafeOPTIONS yes yesGET yes yesHEAD yes yesPUT yes noPOST no noDELETE yes noPATCH no No, I believe from the above table, you should understand it very well. What is not easy to understand is why patch is not a method idempotent. It is not easy to explain. I will briefly explain here that a patch request will execute a program. If the request is repeated, the program may be executed multiple times, which may have additional impact on the resources on the server side, so it is not a method idempotent.

If you want a deeper understanding, please Google

Shortcomings of restful API remember, there are no perfect things in the world, and there must be some shortcomings. Restful is very convenient. Yes, but as long as users understand the URL structure of your website, they will start to have security problems. Thinking about a problem, it is a terrible thing for a user to arbitrarily operate crud on your database. Think about another problem. Suppose we get a user’s url like this / API / uesrs / 1 /, Generally speaking, users can only access their own user data and cannot view other user data. Otherwise, interested people can try to get other user data from / API / uesrs / 1 / to / API / uesrs / 100 /. This is a basic problem. Usually, we will verify the user’s identity first, and then decide whether we have permission to access the user’s data, so we must deal with the identification of the user again

验证和授权(可参考之前在 诶jango-rest-framework-tutorial (https://github.com/twtrubiks/django-rest-framework-tutorial#%E6%8E%88%E6%AC%8A-authentications-)里介绍的授权),然后使用 HTTPS。

Let’s talk about another problem. Many of them are front-end and back-end separation. Usually, we use JSON as the transmission format for convenience, but sometimes we may accidentally send some sensitive information to the front-end, which may lead to data leakage, or interested people can get other people’s data and interesting information through this information. So when you design the API, you must think about whether the information leakage will have any impact. If so, the data may need to be encrypted again. Then think about this problem. Sometimes we have to call the API many times to obtain complete information in order to obtain data. For example, if we want to obtain the information of the article and the author, we will first call get / articles / {ID} / to obtain the author of the article, and then call get / uesrs / {name} / to obtain the author’s information. In this case, I think we can make a small move without strictly abiding by it, In addition, graphql can get all the required data through one query (I’ll introduce this later when I have a chance). Because of the above reasons, it is possible that our API may be inadvertently designed to call another API after calling one API. This kind of design related to connectivity (resulting in more and more chaos in the system), so we should pay attention to these. Let’s assume that we need to design an API for batch deletion today, How to plan? It’s all on the URI. If it exceeds the limit, the last problem is the actual problem. Many times, our business logic is very complex, which will make it not so easy to use if we have to strictly abide by the rules of the restful API. Therefore, sometimes we can make some modifications in the restful API, and we don’t have to abide by its rules.

Users of the status code operation API can understand certain meanings through the HTTP status code. The common situations of HTTP status co AI e are as follows (usually, but not absolutely). 200 OK is used to request success. Get file is successful, put and patch are updated successfully. 201 create is used to request post to successfully create data. 204 no content is used to request delete successfully. 400 bad request is used to request incorrect API parameters, such as the incoming JSON format error. 401 unauthorized indicates that the requested API is missing authentication information. 403 Forbidden is used to indicate that the resource is not allowed to be accessed by specific users. 404 not found is used to request a non-existent resource. For more details, please refer to HTTP status codes

If your API is complex, you should have a file to record your error code.

The necessary information and operation codes of the API are suitable for different HTTP error definitions

(return a JSON and include the error attribute, which records the error message).

Conclusion this time I briefly introduced the concept of restful API to you. Basically, there are still many things to study, such as avoiding API attacks, enabling API call rate limiting, or HTTP cache mechanism. Finally, welcome to the world of restful