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