个有关RESTful API良好设计的最佳实践.docxVIP

10个有关RESTful API良好设计的最佳实践 Resource资源 GET读 POST创建 PUT修改 DELETE /cars 前往 cars集合 创建新的资源 批量更新cars 删除全部cars /cars/711 前往特定的car 该方法不允许(405) 更新一个指定的资源 擅长指定资源 不要使用： /getAllCars/createNewCar/deleteAllRedCars ?2.Get方法和查询参数不应当涉及形态转变 使用PUT, POST?和DELETE?方法?而不是?GET?方法来转变形态，不要使用GET?进行形态转变: GET /users/711?activate?GET /users/711/activate 3.使用复数名词 不要混淆名词单数和复数，为了保持简约，只对全部资源使用复数。 /cars 而不是 /car/users 而不是 /user/products 而不是 /product/settings 而部署 /setting 4. 使用子资源表达关系 假如一个资源与另外一个资源有关系，使用子资源： GET /cars/711/drivers/ 前往 car 711的全部司机GET /cars/711/drivers/4 前往 car 711的4号司机 5.使用Http头声明序列化格式 在客户端和服务端，双方都要晓得通讯的格式，格式在HTTP-Header中指定 Content-Type 定义恳求格式Accept 定义系列可接受的响应格式 6.使用HATEOAS Hypermedia?as?the?Engine?of?Application?State 超媒体作为应用形态的引擎，超文本链接可以建立更好的文本扫瞄： { id: 711, manufacturer: bmw, model: X5, seats: 5, drivers: [ { id: 23, name: Stefan Jauker, links: [ { rel: self, href: /api/v1/drivers/23 } ] } ] } 留意href指向下一个URL 7.为集合供应过滤 排序 选择和分页等功能 Filtering过滤: 使用独一的查询参数进行过滤： GET /cars?color=red 前往红色的carsGET /cars?seats=2 前往小于两座位的cars集合 Sorting排序: 允许针对多个字段排序 GET /cars?sort=-manufactorer,+model 这是前往依据生产者降序和模型升序陈列的car集合 Field selection 移动端能够显示其中一些字段，它们其实不需要一个资源的全部字段，给API消费者一个选择字段的力量，这会降低网络流量，提高API可用性。 GET /cars?fields=manufacturer,model,id,color ? Paging分页 使用 limit 和offset.实现分页，缺省limit=20 和offset=0； GET /cars?offset=10limit=5 为了将总数发给客户端，使用订制的HTTP头： X-Total-Count. 链接到下一页或上一页可以在HTTP头的link规定，遵照Link规定: Link: ; rel=next, ; rel=last, ; rel=first, ;?rel=prev, 8.版本化你的API 使得API版本变得强制性，不要发布无版本的API，使用简约数字，避开小数点如2.5. 一般在Url后面使用?v /blog/api/v1 9. 使用Http形态码处理错误 假如你的API没有错误处理是很难的，只是前往500和出错堆栈不肯定有用 Http形态码供应70个出错，我们只需使用10个左右： 200 – OK – 一切正常201 – OK – 新的资源已经成功创建204 – OK – 资源已经成功擅长 304 – Not Modified – 客户端使用缓存数据 400 – Bad Request – 恳求无效，需要附加细节解释如 JSON无效401 – Unauthorized – 恳求需要用户验证403 – Forbidden – 服务器已经理解了恳求，但是拒绝服务或这种恳求的访问是不允许的。404 – Not found – 没有发觉该资源422 – Unprocessable Entity – 只要服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。 500 – Internal Server Error – API开发者应当避开这种错误。 使用具体的错误