在 REST 中的主数据被称为资源,而正确命名的资源将使 API 易于使用和直观访问。同样的 API,如果实施不正确,可能会让调用者感觉很复杂,并且难以使用和理解。
以下内容将帮助开发者构建正确的 API 构建资源 URI。
始终确保你的 URI 以名词命名指定资源,而不是使用动词。
URI 应指明相关 CRUD(创建、读取、更新、删除)操作。另外请避免动词-名词组合:hyphenated、snake_case、camelCase。
命名不好的例子:
http://api.example.com/v1/store/CreateItems/{item-id}❌
http://api.example.com/v1/store/getEmployees/{emp-id}❌
http://api. example.com/v1/store/update-prices/{price-id}❌
http://api.example.com/v1/store/deleteOrders/{order-id}❌
命名很好的例子:
http://api.example.com/v1/store/items/{item-id} ✅
http://api.example.com/v1/store/employees/{emp-id} ✅
http://api. example.com/v1/store/prices/{price-id} ✅
http://api.example.com/v1/store/orders/{order-id} ✅
尽可能使用复数表示资源,除非它们是单例资源。
命名不好的例子(典型和单例资源):
http://api.example.com/v1/store/item/{item-id}❌
http://api.example.com/v1/store/employee/{emp-id}/address❌
命名很好的例子(典型和单例资源):
http://api.example.com/v1/store/items/{item-id} ✅
http://api.example.com/v1/store/employees/{emp-id}/address ✅
注意,不要使用下划线。用连字符分隔单词会让自己和其他人更容易理解。当涉及到长路径分段 URI 时,它更加显得用户友好。
命名不好的例子:
http://api.example.com/v1/store/vendormanagement/{vendor-id}❌
http://api.example.com/v1/store/itemmanagement/{item-id}/producttype❌
http:// api.example.com/v1/store/inventory_management❌
命名很好的例子:
http://api.example.com/v1/store/vendor-management/{vendor-id} ✅
http://api.example.com/v1/store/item-management/{item-id}/product-输入✅
http://api.example.com/v1/store/inventory-management ✅
正斜杠用于显示单个资源和集合之间的层次结构。
命名不好的例子:
http://api.example.com/v1/store/items/❌
命名很好的例子:
http://api.example.com/v1/store/items ✅
避免使用文件扩展名
这些扩展名不是必要的,并且会增加 URI 的长度和复杂性。
命名不好的例子:
http://api.example.com/v1/store/items.json❌
http://api.example.com/v1/store/products.xml❌
命名很好的例子:
http://api.example.com/v1/store/items ✅
http://api.example.com/v1/store/products ✅
始终对你的 API 进行版本控制。你可以通过对 API 进行版本控制来提供升级路径,而无需对现有 API 进行任何彻底性更改。你还可以让用户知道 API 的更新版本可通过以下完全限定的 URI 访问。
http://api.example.com/v1/store/employees/{emp-id}
使用 /v2 可以避免引入任何重大的更新。
http://api.example.com/v1/store/items/{item-id}
http://api.example.com/v2/store/employees/{emp-id}/address
开发者会经常遇到要求根据特定资源属性对一组资源进行排序、过滤或限制的需求。无需创建额外的 API,而是在资源集合 API 中启用排序、过滤和分页,并将输入参数作为查询参数来满足此需求。
http://api.example.com/v1/store/items?group=124
http://api.example.com/v1/store/employees?department=IT®ion=USA
GET — 读取员工 ID 为 8345 的员工
example.com/employees/8345
POST——创建员工
example.com/employees
PUT - 使用员工 ID 8345 更新员工信息
example.com/employees/8345
DELETE — 删除员工 ID 为 8345 的员工记录
example.com/employees/8345
作者:李龙飞