关于http:Restful接口规范

67次阅读

共计 2578 个字符,预计需要花费 7 分钟才能阅读完成。

REST 接口标准
1、动作
GET(SELECT):从服务器检索特定资源,或资源列表。
POST(CREATE):在服务器上创立一个新的资源。
PUT(UPDATE):更新服务器上的资源,提供整个资源。
PATCH(UPDATE):更新服务器上的资源,仅提供更改的属性。
DELETE(DELETE):从服务器删除资源。
首先是四个半种动作:
post、delete、put/patch、get
因为 put/patch 只能算作一类,所以将 patch 归为半个。
另外还有有两个较少出名的 HTTP 动词:
HEAD – 检索无关资源的元数据,例如数据的哈希或上次更新工夫。
OPTIONS – 检索对于客户端被容许对资源做什么的信息。
2、门路(接口命名)
门路又称 ” 起点 ”(endpoint),示意 API 的具体网址。
在 RESTful 架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的 ” 汇合 ”(collection),所以 API 中的名词也应该应用复数。
举例来说,有一个 API 提供动物园(zoo)的信息,还包含各种动物和雇员的信息,则它的门路应该设计成上面这样。
接口尽量应用名词,禁止应用动词,上面是一些例子。

GET /zoos:列出所有动物园
POST /zoos:新建一个动物园
GET /zoos/ID:获取某个指定动物园的信息
PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全副信息)
PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的局部信息)
DELETE /zoos/ID:删除某个动物园
GET /zoos/ID/animals:列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物
反例:
/getAllCars
/createNewCar
/deleteAllRedCars
再比方,某个 URI 是 /posts/show/1,其中 show 是动词,这个 URI 就设计错了,正确的写法应该是 /posts/1,而后用 GET 办法示意 show。
如果某些动作是 HTTP 动词示意不了的,你就应该把动作做成一种资源。比方网上汇款,从账户 1 向账户 2 汇款 500 元,谬误的 URI 是:
POST /accounts/1/transfer/500/to/2
正确的写法是把动词 transfer 改成名词 transaction,资源不能是动词,然而能够是一种服务:
POST /transaction HTTP/1.1
Host: 127.0.0.1
from=1&to=2&amount=500.00

理清资源的层次结构,比方业务针对的范畴是学校,那么学校会是一级资源 (/school),老师(/school/teachers),学生(/school/students) 就是二级资源。
3、版本(Versioning)
应该将 API 的版本号放入 URL。如:
https://api.example.com/v1/
另一种做法是,将版本号放在 HTTP 头信息中,但不如放入 URL 不便和直观。Github 采纳这种做法。
4、过滤信息(Filtering)
如果记录数量很多,服务器不可能都将它们返回给用户。API 应该提供参数,过滤返回后果。
上面是一些常见的参数。

?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始地位。?page_number=2&page_size=100:指定第几页,以及每页的记录数。?sortby=name&order=asc:指定返回后果依照哪个属性排序,以及排序程序。?animal_type_id=1:指定筛选条件
参数的设计容许存在冗余,即容许 API 门路和 URL 参数偶然有反复。比方,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含意是雷同的。

5、状态码(Status Codes)
状态码范畴

1xx 信息,申请收到,持续解决。范畴保留用于底层 HTTP 的货色,你很可能永远也用不到。2xx 胜利,行为被胜利地承受、了解和驳回
3xx 重定向,为了实现申请,必须进一步执行的动作
4xx 客户端谬误,申请蕴含语法错误或者申请无奈实现。范畴保留用于响应客户端做出的谬误,例如。他们提供不良数据或要求不存在的货色。这些申请应该是幂等的,而不是更改服务器的状态。5xx 范畴的状态码是保留给服务器端谬误用的。这些谬误经常是从底层的函数抛出来的,甚至
开发人员也通常没法解决,发送这类状态码的目标以确保客户端取得某种响应。当收到 5xx 响应时,客户端不可能晓得服务器的状态,所以这类状态码是要尽可能的防止。

服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的 HTTP 动词)。

200 OK - [GET]:服务器胜利返回用户申请的数据,该操作是幂等的(Idempotent)。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 - [*]:服务器产生谬误,用户将无奈判断收回的申请是否胜利。502 网关谬误
503 Service Unavailable
504 网关超时

正文完
 0