RESTful API 如何设计

Posted 2021-01-02 queqp

1、协议

尽量使用 HTTPS

 

2、’域名

尽量将API部署在专用域名之下

如果API很简单，不会有进一步扩展，可以考虑放在主域名下

 

3、版本

应该将版本放在URL中 ，例如 https://api.xxx.com/v1

 

4、路径

每个网址，就是一种资源，所以不能有动词，只能有名词

 

5、HTTP动词

对于资源的具体操作类型，由http动词表示

常用的有5个

GET,POST,PUT,PATCH,DELETE

HEAD 获取资源元数据

OPTIONS 获取信息，关于资源哪些属性是客户端可以改变的

 

6、过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果

limit   offset page per_page 

 

7、状态码

 

8、错误处理

如果状态 4xx ，就应该想用户返回出错信息。一般来说，返回的信息中奖error作为键名

 

9、返回结果

• GET /collection：返回资源对象的列表（数组）
• GET /collection/resource：返回单个资源对象
• POST /collection：返回新生成的资源对象
• PUT /collection/resource：返回完整的资源对象
• PATCH /collection/resource：返回完整的资源对象
• DELETE /collection/resource：返回一个空文档

10、Hypermedia API

 

11、其他

身份认证，应该使用 oauth2.0

返回数据格式，尽量使用 JSON