独家 | 提升API设计技能的22个最佳实践（附链接）
翻译：张一然
校对：和中华
本文约2000字，建议阅读7分钟
本文介绍了有关设计REST api的一些实用建议。
/systemOrders 或者 /system_orders/system-orders/system-orders/{order_id} 或者 /system-orders/{OrderId}/system-orders/{orderId}GET /user 或者 GET /UserGET /usersGET /shops/:shopId/category/:categoryId/priceGET /shops/:shopId/ 或者 GET /category/:categoryIdPOST /updateuser/{userId} or GET /getusersPUT /user{userId}POST /alerts/245743/resend{user_name: "Mohammad Faisal"user_id: "1"}{userName: "Mohammad Faisal"userId: "1"}product_orderproduct-orders因为这会无意间暴露底层架构。
API Blueprint
Swagger
http://api.domain.com/v1/shops/3/products
{users: [ ...]}{ users: [ ... ],total: 34}
GET /shops?offset=5&limit=5GET /shops?fields=id,name,address,contactGET /shops/123?token=some_kind_of_authenticaiton_tokenAuthorization: Bearer xxxxxx, Extra yyyyyGET：检索资源的表示。
POST：创建新资源和子资源。
PUT：更新现有资源。
PATCH：更新现有资源。它只更新提供的字段，其他字段不理会
DELETE：删除现有资源。
GET /shops/2/products ：从商店 2 获取所有产品的列表。
GET /shops/2/products/31：获取店铺2中商品31的详细信息
DELETE /shops/2/products/31 ，应该删除店铺 2 中的产品 31。
PUT /shops/2/products/31 ，应该更新产品 31 的信息，只在资源 URL 上使用 PUT，而不是集合URL。
POST /shops ，应该创建一个新商店并返回创建的新商店的详细信息。在集合 URL 上使用 POST。
由于一个或多个服务错误而拒绝客户端请求时，请务必返回 4xx HTTP 错误代码。
考虑处理所有属性，然后在单个响应中返回多个验证问题。
扁平比嵌套好。
简单胜于复杂。
字符串比数字好。
一致性优于定制。
译者简介
张一然，哥本哈根大学计算机系硕士毕业, 研究方向为图像补全。现从事自然语言处理工作。感兴趣方向为计算机视觉和自然语言处理，喜欢看书旅游。
翻译组招募信息
工作内容：需要一颗细致的心，将选取好的外文文章翻译成流畅的中文。如果你是数据科学/统计学/计算机类的留学生，或在海外从事相关工作，或对自己外语水平有信心的朋友欢迎加入翻译小组。
你能得到：定期的翻译培训提高志愿者的翻译水平，提高对于数据科学前沿的认知，海外的朋友可以和国内技术应用发展保持联系，THU数据派产学研的背景为志愿者带来好的发展机遇。
其他福利：来自于名企的数据科学工作者，北大清华以及海外等名校学生他们都将成为你在翻译小组的伙伴。
点击文末“阅读原文”加入数据派团队~
转载须知
发布后请将链接反馈至联系邮箱（见下方）。未经许可的转载以及改编者，我们将依法追究其法律责任。
点击“阅读原文”拥抱组织