[Python知识库]Django REST Framework API和RESTful接口规范

API

API是指某个应用程序封装好的一些函数，是提供给其他应用程序或开发人员使用的。通过API，可以方便的使用的本应用程序的功能，而无需了解本应用程序的内部源码。

Web API是API中的一类，它的功能与广义上的API是一样的，只是它提供给外界的是一些url规则而非函数，包括下面4个部分：

url：url链接；
请求方式：get、post、patch、delete等；
请求参数：json或xml格式的key-value类型数据；
响应结果：json或xml格式的key-value类型数据。

RESTful接口规范

REST是REpresentational State Transfer（表述性状态转移）的首字母缩写。它是分布式超媒体系统的架构风格，最初由Roy Fielding在2000年的论文中提出。

1.什么是RESTful：

REST-ful,其中ful代表形容词，如helpful、powerful。这类形容词意为"full of,having the quality of"。多加在名词之后表示“充满…的、易于…、可…的、富有…的、具有…的”的意思，是最常用的形容词后缀，反义词后缀是-less。RESTful 就代表满足REST原则的

参考自：RESTful API

2.?什么是RESTful规范

REST指的是一组架构约束条件和原则，通常用于Web服务的开发。它没有提出具体的实现，只是提出了一些指导规范，供我们开发时参考。我们可以按照它的规范来，也可以忽视（不建议）。

如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

3.RESTful API 设计指南

安全保障
为了安全起见，应该使用https协议。

4.表识API

用api关键字标识api url，与普通url加以区别。如：

www.xyz.com/api/xxx/，api.xyz.com/xxx/

5.版本控制

在url中添加版本版本，或者将版本信息放在请求头中，请求同一资源的不同版本。如：

api.xyz.com/v1/xxx，Accept: application/vnd.xyz+json;version=1.0。

6.路径

数据即是资源，应当使用名词（可用复数形式）。如：www.xyz.com/book/。

HTTP动词，即请求方法（method）
对资源的操作由请求方式决定！

幂等性：对同一REST接口的多次访问，得到的资源状态是相同的。

安全性：对该REST接口访问，不会使服务端资源的状态发生改变。

7.过滤

通过在url上传递参数的形式提交过滤条件。如：

https://api.example.com/v1/zoos?limit=10：指定返回记录的数量

https://api.example.com/v1/zoos?offset=10：指定返回记录的开始位置

https://api.example.com/v1/zoos?page=2&per_page=100：指定第几页，以及每页的记录数

https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序

https://api.example.com/v1/zoos?animal_type_id=1：指定筛选条件

HTTP状态码
1xx（信息）：通信传输协议级信息
1XX系列响应代码仅在与HTTP服务器沟通时使用，平常极少使用。

2xx（成功）：表示客户端的请求已成功接受
200（OK）：表示REST API成功执行了客户端请求的任何操作；

201（ Created）：用户新建资源成功。

202（Accpted）：已经接受请求并加入了处理队列，但处理尚未完成。

204（No Content）：服务器成功处理，但没有内容可返回。常用于PUT、POST或者DELETE请求的响应。

204响应绝不能包含消息体，因此总是在头字段之后的第一个空行终止。

3xx（重定向 ）：表示客户端必须执行一些其他操作才能完成其请求
301（Moved Permanently）：请求的URL已永久移走，并设计了新的URL，客户端应该使用新的URL。

REST API应在响应的Location头中指定新的URL，并且将旧的URL请求都定向到新的URL。

302（Found）：与301类似，但资源只是临时被移动，客户端应继续使用原有URL。

302 是执行URL重定向的常用方式。

304（Not Modified）：如果客户端在发送GET请求时附上if-Modified-Since报头，并且从报头指定版本开始从未修改过该资源，则说明客户端的缓存资源是最新的， 要求客户端使用缓存以节省资源。

此状态代码类似于204，响应正文必须为空。

4xx（客户端错误）：此类错误状态代码指向客户端
400（Bad Request）：这是一个通用的客户端错误状态，表示客户端请求的语法错误，服务器无法理解。

401（Unauthorized）：客户端试图对一个受保护的资源进行操作，却没有提供正确的认证证书（令牌、用户名、密码错误）。

响应必须包含WWW-Authenticate头字段，其中包含适服务器将接受哪种认证。

403（Forbidden）：与401错误相对，表明客户端的请求是正确的，但用户没有资源的必要权限。

该响应代码常用于一个资源只允许在特定时间段内访问，或者允许特定IP地址的用户访问的情况。

404（Not Found）：服务器无法根据客户端的请求找到资源（网页）。

405（Method Not Allowd）：客户端尝试使用资源不允许的HTTP方法。比如，一个资源只支持GET方法，但是客户端使用PUT方法访问。

405响应必须包含Allow标头，该标头列出资源支持的HTTP方法。

406（Not Acceptable）：用户请求的格式不可得。比如用户请求JSON格式，但是只有XML格式。

5xx（服务器错误）：服务器负责这些错误状态代码
500（Internal Server Error）：这是一个通用的服务器错误响应。对于大多数web框架，如果在执行请求处理代码时遇到了异常，它们就发送此响应代码。
?