restfulurl设计规范_RESTful设计⽅法和规范
RESTful设计⽅法和规范
在初步了解了 RESTful 之后，我们接到⼀项任务，需要为⼀所学校开发⼀套师⽣管理系统，客户要求所开发的系统能在 PC 桌⾯通过浏览器使⽤，⽽且⽇后还想开发 IOS 和 Android 应⽤。了解需求之后，我们毫不犹豫选择了前后端分离的开发模式，并且决定遵从时下最为流⾏的 RESTful 规范。接下来，我们就以后端开发⼈员的⾓⾊，⼀起来了解整个开发过程。
1. 域名(Domain)
根据 RESTful 规范，应该尽量使⽤专⽤的域名⽤于部署 API，于是我们和校⽅沟通，使⽤下⽅域名作为 API 访问地址：
但是经过沟通，发现上述域名已被占⽤，校⽅否决了我们的提议，考虑到 API 相对简单，于是我们使⽤下⾯地址部署 API：
上述地址中，https 代表协议名称，常见的还有 http，⼆者区别在于前者在传输过程中是将信息加密后传输的，⽽后者是明⽂传输；api 代表⼀个资源路径，可以想象成这台电脑中⼀个⽂件夹的路径。
2. 版本(Versioning)
师⽣管理系统不是⼀成不变的，⽇后还要更新维护。为了区分不同版本，API 的 URL 中应当包含 API 版本信息：
除了上述⽅法外，API 版本信息还可放在 HTTP 请求头中。Github 采⽤的就是这种做法。
因为不同的版本，可以理解成同⼀种资源的不同表现形式，所以应该采⽤同⼀个 URL。版本号可以在 HTTP 请求头信息的 Accept 字段中进⾏区分(参见Versioning REST Services)：
实际⼯作中，通常采⽤第⼀种⽅法，因为这样的⽅式更加直观，⽅便使⽤。
3. 路径(Endpoint)
路径即”终点”(endpoint)，是访问 API 的具体⽹址，通过访问每个⽹址，可以获取到相应的资源(resource)。在师⽣管理系统中，所谓资源，就是我们想获取的信息，⽐如获取 3 年 2 班所有学⽣姓名，获取⼩明的年龄、成绩等。
路径须满⾜以下规范：
1. 资源路径中应当使⽤名词，杜绝动词。资源路径中的名词，应当与数据库的表名相对应。
以下路径中包含动词，是不符合规范的例⼦，在实际⼯作中，应当避免。
对于资源的操作，应该通过 HTTP 中的不同⽅法来区分处理资源的动作，资源路径中应当只包含名词。
2. API 中的名词应该使⽤复数。⽆论是⼦资源或者是所有资源。
例如：
4. HTTP动词
对于资源的具体操作类型，由 HTTP 动词表⽰。
常⽤的 HTTP 动词有下⾯ 4 个(括号⾥是对应的 SQL 命令)。
GET(SELECT)：从服务器取出资源(⼀项或多项)
url编码处理POST(CREATE)：在服务器新建⼀个资源
PUT(UPDATE)：在服务器更新资源(客户端提供改变后的完整资源)
DELETE(DELETE)：从服务器删除资源
还有 3 个不常⽤的 HTTP 动词。
PATCH(UPDATE)：在服务器更新(更新)资源(客户端提供改变的属性)
HEAD：获取资源的元数
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的
下⾯是⼀些例⼦。
5. 过滤信息(Filtering)
如果记录数量很多，服务器不可能都将它们返回给⽤户。API 应该提供参数，过滤返回结果。⽐如，我们想获取全校师⽣的个⼈信息，如果将这些信息⼀股脑地全部展⽰在⽹页上，是不明智也是不现实的。如果数据量太⼤，在实际开发中我们会采⽤分页展⽰的形式。另外，如果想在⼀次考试后，按照成绩⾼低展⽰学⽣信息，那么可以通过过滤信息来实现。
所谓过滤，就是在 URL 中添加⼀下限制参数。下⾯是⼀些常见的参数。
参数的设计允许存在冗余，即允许 API 路径和 URL 参数允许有重复。⽐如，想要查询某个班级所有学⽣信息，我们可以设计 GET
/classes/ID/students 与 GET /students?class_id=ID 两种地址，任何⼀种都可得到相同的结果。
为什么上⾯的两种路径的请求结果⼀样呢，可以在这⾥说明⼀下。
6. 状态码(Status Codes)
服务器向⽤户返回的状态码和提⽰信息，常见的有以下⼀些(⽅括号中是该状态码对应的 HTTP 动词)。不同的状态码代表着不同的含义，⽐如以 2 开头的状态码通常代表服务器成功响应，3 开头的状态码代表发⽣了重定性(即跳转到了别的链接)，4 开头的状态码通常表⽰客户端这边提供的信息有误，⽽ 5 开头的状态码则表⽰服务器内部出现的错误。通过返回的状态码，⽤户即可判断请求成功与否，不成功问题在何处。
⼀些常⽤的状态码列举如下：
200 OK – [GET]：服务器成功返回⽤户请求的数据
201 CREATED – [POST/PUT/PATCH]：⽤户新建或修改数据成功。
202 Accepted – [*]：表⽰⼀个请求已经进⼊后台排队(异步任务)
204 NO CONTENT – [DELETE]：⽤户删除数据成功
400 INVALID REQUEST – [POST/PUT/PATCH]：⽤户发出的请求有错误，服务器没有进⾏新建或修改数据的操作
401 Unauthorized – [*]：表⽰⽤户没有权限(令牌、⽤户名、密码错误)
403 Forbidden – [*] 表⽰⽤户得到授权(与401错误相对)，但是访问是被禁⽌的
404 NOT FOUND – [*]：⽤户发出的请求针对的是不存在的记录，服务器没有进⾏操作，该操作是幂等的
406 Not Acceptable – [GET]：⽤户请求的格式不可得(⽐如⽤户请求JSON格式，但是只有XML格式)
410 Gone -[GET]：⽤户请求的资源被永久删除，且不会再得到的
422 Unprocesable entity – [POST/PUT/PATCH]： 当创建⼀个对象时，发⽣⼀个验证错误
500 INTERNAL SERVER ERROR – [*]：服务器发⽣错误，⽤户将⽆法判断发出的请求是否成功
状态码的完全列表参见这⾥或这⾥。
7. 错误信息
如果状态码是 4xx，服务器就应该向⽤户返回出错信息。⼀般来说，返回的信息是键值对形式的数据，将 error 作为键名，出错信息作为键值即可。⽐如，在⼀个提供查询学⽣信息的 API 中，要求客户端提供正确的 API key(可以理解为输⼊了正确的⽤户名和密码)才能访问，如果提供的 API key 不正确，此时服务器应拒绝访问，并返回错误信息。这样，客户端就知道了为何没能查到信息，修改成正确的 API key 即可。
8. 返回结果
针对不同操作，服务器向⽤户返回的结果应该符合以下规范。
GET /collection：返回资源对象的列表(数组)
GET /collection/resource：返回单个资源对象
POST /collection：返回新⽣成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回⼀个空⽂档
9. 超媒体链接
RESTful API 最好做到 Hypermedia(即返回结果中提供链接，连向其他 API ⽅法)，使得⽤户不查⽂档，也知道下⼀步应该做什么。
⽐如，Github 的 API 就是这种设计，访问api.github会得到⼀个所有可⽤API的⽹址列表。
从上⾯可以看到，如果想获取当前⽤户的信息，应该去访问 api.github/user，然后就得到了下⾯结果。
上⾯代码表⽰，服务器给出了提⽰信息，以及⽂档的⽹址。
10. 数据格式
服务器返回的数据格式，应该尽量使⽤ JSON，避免使⽤ XML。什么是 JSON 呢？什么⼜是 XML 呢？两种数据格式的简单举例如下：
通过上⾯的对⽐可以看出，JSON 数据形式要远⽐ XML 的数据形式来得简单和易懂，所以现在的 Web 开发中 JSON 数据格式已经开始全⾯取代 XML 应⽤在实际开发中。
11. ⼩结
本节主要从域名、版本、路径、HTTP动词、过滤信息、状态码、错误信息、返回结果、超媒体链接、数据格式 10 个⽅⾯介绍了 RESTful 设计⽅法和设计规范。为了让更多的⼈⽅便使⽤所设计的 API 接⼝，以上规范⼀定要遵守哦！

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。