4.3 KiB
title | localeTitle |
---|---|
Rest API Design | Rest API设计 |
历史
REST代表Re presentational S tate T ransfer协议。 Roy Fielding在2000年的博士论文中定义了REST。
它是什么?
开发REST是为了提供统一的界面
- 识别资源
- 操纵资源
- 自描述信息
- 使用超媒体作为应用程序状态引擎(HATEOS)
最佳实践
- #### 基本
|方法| http://api.co/v2/cars | http://api.co/v2/cars/1234 |
| --- | --- | --- | | GET |列出所有的汽车|检索单个汽车| | POST |制造新车|错误| | PUT |用新的替换汽车收藏|更换id为1234 |的汽车 |删除|删除所有汽车|删除ID为1234 |的汽车
注意,当客户端或服务器的PUT操作可以生成id
-
名词很好动词很糟糕
-
使用名词来引用
cars
,fruits
等资源。 -
使用动词声明动作声明
convertMilesToKms
,getNutritionalValues
-
单数还是复数?
使用正确的语法进行声明
避免
/person/145
首选
/people/154
假设从人名单中返回第154个人 -
使用套管
使用以下任何一种模式并保持一致!
|案例样式|示例| | ------------- | ------------- | | UpperCamelCase |
http://api.fintech.cp/DailyTransactions/Today
| | lowerCamelCase |http://api.fintech.cp/dailyTransactions/today
|
| snake_case |http://api.fintech.cp/daily_transactions/today
| -
关系和资源
-
资源可以具有
one-to-many
,many-to-many
,many-to-one
关系等。正确映射它们至关重要。 -
一对多映射
例如,
Tickets/145/messages/4
表明tickets
和messages
之间的一对多关系。含义1
票有N
消息。消息不是独立资源。你不能拥有/messages/4
。 -
多对多映射
例如,
/usergroups/345/users/56
建议选择第345个用户组并获取id为56的用户。但是,一个用户可能在多个usergroups
即/usergroups/209/users/56
也有效。在这种情况下,将depedant资源users
分成一个单独的端点,如/users/56
并在/usergroups/209/users/56
提供资源链接 -
API参数
-
PATH: _需要_访问资源如
/cars
,/fruits
-
查询参数 : _可选_过滤列表Eg
/cars?type=SUV&year=2010
-
正文 :资源特定逻辑。高级搜索查询。有时它可能同时具有Query和body。
-
标题 :应包含全局或平台范围的数据。例如API密钥参数,用于auth的加密密钥,设备类型信息,例如移动或桌面或端点,设备数据类型,例如xml或json。使用标头来传达这些参数
-
HTTP状态代码
使用正确的状态代码
|代码|意义| | ------------- |:-------------:| | 1xx |收到并理解请求。 | | 2xx |收到,理解并要求客户要求采取的行动。 | | 3xx |客户必须采取其他措施来完成请求。大多数这些状态代码用于URL重定向。 | | 4xx |适用于似乎错误是由客户端引起的情况。 | | 5xx |服务器无法满足请求。 |
关于2xx的更多信息!
-
201资源创建。 POST
/cars
应返回使用location
标头创建的HTTP 201,说明如何访问资源 例如location
:头文件中的api.com/cars/124
-
202 - 接受
如果任务很大,请使用此选项。告诉客户,它已接受请求并将/正在处理/处理 没有返回有效负载
-
204 - 没有内容
删除
DELETE cars/124
不返回任何内容。但是如果API打算发送已删除的资源以供进一步处理,也可以返回200 OK
。危险的5xx资源!
-
500内部服务器错误
-
504网关超时。服务器未及时收到响应
鲜为人知的4xx表明您传递了错误的参数。也可以传递错误的信息。例如
DELETE /cars/MH09234
返回
4xx
或消息Expecting int car id /car/id got string car/MH09234