RESTful API 设计规范

RESTful API 设计规范旨在提供一种简单、灵活、可伸缩的通信方式，它基于资源的设计风格，并通过标准的HTTP方法（如GET、POST、PUT、DELETE）对资源进行操作。以下是RESTful API设计规范的详细内容：

一、设计原则

    客户端-服务器架构：RESTful API 遵循客户端-服务器架构，使得服务器端的资源能够被客户端访问。
    无状态：RESTful API 不保存客户端的状态，所有的状态都保存在客户端。这意味着每次请求都应该包含所有必要的信息，以便服务器能够理解和处理请求。
    统一接口：RESTful API 使用 HTTP 协议提供统一的接口，使得客户端能够跨平台访问服务器端的资源。
    可扩展性：RESTful API 应该支持扩展，以便能够适应未来的变化。

二、设计规范

    协议：API与用户的通信协议应使用HTTPs协议或HTTP协议，并统一确定使用其中一种。
    域名：应尽量将API部署在专用域名之下，如https://api.XXXXXX.com。如果多个项目创建API，可以在域名中带上项目名称，如https://greapi.XXXXXX.com。
    版本：可以将版本号放在HTTP头信息中，也可以放入URL中，如https://api.XXXXXX.com/v1/，或者加入参数中。
    路径：路径是一种地址，在互联网上表现为网址。在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。通常，API中的名词应该使用复数形式，如https://api.XXXXXX.com/v1/students。
    HTTP动词：对于资源的具体操作类型，由HTTP动词表示。主要动词包括：
        GET（SELECT）：从服务器取出资源（一项或多项）。
        POST（CREATE）：在服务器新建一个资源。
        PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
        PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
        DELETE（DELETE）：从服务器删除资源。
        HEAD：获取资源的元数据。
        OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
    过滤信息：如果记录数量很多，服务器不可能都将它们返回给用户，API会提供参数，过滤返回结果。
    状态码：使用HTTP协议的状态码来表示API请求的结果，如200 OK、201 Created、404 Not Found等。
    内容协商：使用HTTP协议的内容协商机制来支持多种格式的资源表示，如JSON、XML等。
    可缓存性：RESTful API 应该支持缓存，以便提高访问效率。
    命名规范：尽量使用资源的名词来命名 URI，而不是动词。避免在 URI 中使用复杂的查询字符串，尽量使用路径参数来表示资源。

附：http状态码相关

状态码范围

客户端的每一次请求, 服务器端必须给出回应，回应一般包括HTTP状态码和数据两部分。

1xx: 信息，请求收到了，继续处理。
2xx: 代表成功. 行为被成功地接收、理解及采纳。
3xx: 重定向。
4xx: 客户端错误，请求包含语法错误或请求无法实现。
5xx: 服务器端错误.

2xx 状态码

200 OK [GET]: 服务器端成功返回用户请求的数据。
201 CREATED [POST/PUT/PATCH]: 用户新建或修改数据成功。
202 Accepted 表示一个请求已经进入后台排队(一般是异步任务)。
204 NO CONTENT -[DELETE]: 用户删除数据成功。

4xx状态码

400：Bad Request - [POST/PUT/PATCH]: 用户发出的请求有错误，服务器不理解客户端的请求，未做任何处理。
401: Unauthorized; 表示用户没有权限(令牌、用户名、密码错误)。
403：Forbidden: 表示用户得到授权了，但是访问被禁止了, 也可以理解为不具有访问资源的权限。
404：Not Found: 所请求的资源不存在，或不可用。
405：Method Not Allowed: 用户已经通过了身份验证, 但是所用的HTTP方法不在它的权限之内。
406：Not Acceptable: 用户的请求的格式不可得(比如用户请求的是JSON格式，但是只有XML格式)。
410：Gone - [GET]: 用户请求的资源被转移或被删除。且不会再得到的。
415: Unsupported Media Type: 客户端要求的返回格式不支持，比如，API只能返回JSON格式，但是客户端要求返回XML格式。
422：Unprocessable Entity: 客户端上传的附件无法处理，导致请求失败。
429：Too Many Requests: 客户端的请求次数超过限额。

5xx 状态码

5xx 状态码表示服务器端错误。

500：INTERNAL SERVER ERROR; 服务器发生错误。
502：网关错误。
503: Service Unavailable 服务器端当前无法处理请求。
504：网关超时。

遵循以上规范，可以设计出符合 RESTful 标准的 API，为不同系统之间提供简单、灵活、可伸缩的通信方式。