RESTful

RESTful API 是什么？

什么是 REST

REST 的全称是 Representational state transfer

• Representational：数据的表现形式（JSON、XML...）
• state：当前状态或者数据
• transfer：数据传输

它描述了一个系统如何与另一个交流。比如一个产品的状态（名字，详情）表现为 XML，JSON 或者普通文本

REST 有六个约束：

• Client—Server（客户端——服务器端）
• Stateless（无状态）
• Cache（缓存）
• Uniform Interface（统一接口）
• Layered System（分层系统）
• Code-On-Demand（按需代码）

最佳实践

请求设计规范

• URI 使用名词，尽力使用复数，如 /users
• URI 使用 嵌套 表示 关联关系，如 /users/123/repos/234
• 使用 正确的 HTTP 方式，如 GET/POST/PUT/DELETE

相应设计规范

• 查询
• 分页
• 字段过滤

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

?limit=10:指定返回记录的数量
?offest=10:指定返回记录的开始位置
?page=2&pre_page=100:指定第几页，以及每页的记录数
?sortby=name&order=asc:指定返回结果按照哪个属性排序，以及排序顺序
?animal_type_id=1:指定筛选条件

• 状态码
• 错误处理

就像 HTML 的错误页面向访问者展示了有用的错误消息一样，API 也应该用之前清晰易读的格式来提供有用的错误消息