资源:资源是数据的一部分,例如:用户
集合:一组资源称为集合,例如:用户列表
URL:标识资源或集合的位置,例如:/user
1. 对URL使用kebab-case(短横线小写隔开形式)
/systemOrders或/system_orders
/system-orders
2. 参数使用camelCase(驼峰形式)
例如,如果你想从一个特定的商店购买产品。/system-orders/{order_id}
/system-orders/{OrderId}
/system-orders/{orderId}
GET /user
GET /User
GET /users
4. URL以集合开始,以标识符结束
GET /shops/:shopId/category/:categoryId/price
GET /shops/:shopId/或GET /category/:categoryId
5. 让动词远离你的资源URL
POST /updateuser/{userId}
GET /getusers
PUT /user/{userId}
POST /alarm/245743/resend
{
user_name: 'Mohammad Faisal'
user_id: '1'
}
{
userName: 'Mohammad Faisal'
userId: '1'
}
8. 监控
product_order
product-orders
API蓝图:https://apiblueprint.org/
Swagger:https://swagger.io/
11. 使用简单序数作为版本
12. 在你的响应体中包括总资源数
如果API返回一个对象列表,则响应中总是包含资源的总数。你可以为此使用total属性。{
users: [
...
]
}
{
users: [
...
],
total: 34
}
13. 接受limit和offset参数
GET /shops?offset=5&limit=5
GET /shops?fields=id,name,address,contact
GET /shops/123?token=some_kind_of_authenticaiton_token
Authorization: Bearer xxxxxx, Extra yyyyy
content-type: application/json
GET /shops/2/products:从shop 2获取所有产品的列表。
GET /shops/2/products/31:获取产品31的详细信息,产品31属于shop 2。
DELETE /shops/2/products/31:应该删除产品31,它属于商店2。
PUT /shops/2/products/31:应该更新产品31的信息,只在resource-URL上使用PUT,而不是集合。
POST /shops:应该创建一个新的商店,并返回创建的新商店的详细信息。在集合url上使用POST。
避免将用户凭证与原始验证相结合。
考虑处理所有属性,然后在单个响应中返回多个验证问题。
扁平比嵌套好。
简单胜于复杂。
字符串比数字好。
一致性比定制更好。
译者:Mr.lzc,软件工程师、DevOpsDays、HDZ深圳核心组织者,目前供职于华为,从事云计算工作,专注于K8s、微服务领域。
作者:刘志超
联系客服