Apiato 应用程序-入门-约束规则
RESTful API 中的 HTTP 方法用法#
- GET(SELECT):从服务器或资源列表中检索特定资源。
- POST(CREATE):在服务器上创建一个新资源。
- PUT(UPDATE):更新服务器上的资源,提供整个资源。
- PATCH(UPDATE):更新服务器上的资源,仅提供更改的属性。
- DELETE(DELETE):从服务器中删除资源。
路由和操作的命名约定#
GetAllResource
:获取所有资源。您可以应用?search
查询参数来过滤数据。FindResourceByID
:通过其唯一标识符搜索单个资源。CreateResource
:创建新资源。UpdateResource
:更新 / 编辑现有资源。DeleteResource
:删除资源。
RESTful URL 的一般准则和原则#
- URL 标识资源。
- 网址应包含名词,而不是动词。
- 使用复数名词只是为了一致性(没有单数名词)。
- 使用 HTTP 谓词(GET,POST,PUT,DELETE)对集合和元素进行操作。
- 您不应该比资源 / 标识符 / 资源更深入。
- 例如,将版本号放在 URL 的底部
http://apiato.develop/v1/path/to/resource
。 - 如果输入数据更改了端点的逻辑,则应在 URL 中传递。如果没有可以进入标题 “像 Auth Token”。
- 不要使用查询参数来改变状态。
- 如果可以帮助,请不要使用混合案例路径;小写是最好的。
- 不要在 URI 中使用特定于实现的扩展名(.php,.py,.pl 等)
- 尽可能限制 URI 空间。并保持路径段短。
- 不要将元数据放在应该位于标题中的响应主体中
好的 URL 示例#
-
通过其唯一标识符(ID)查找单个 Car:
GET http://www.api.apiato.develop/v1/cars/123
-
获取所有汽车:
GET http://www.api.apiato.develop/v1/cars
-
通过一个或多个字段查找 / 搜索汽车:
GET http://www.api.apiato.develop/v1/cars?search=maker:mercedes
GET http://www.api.apiato.develop/v1/cars?search=maker:mercedes;color:white
-
订单和排序查询结果:
GET http://www.api.apiato.develop/v1/cars?orderBy=created_at&sortedBy=desc
GET http://www.api.apiato.develop/v1/cars?search=maker:mercedes&orderBy=created_at&sortedBy=desc
-
指定可选字段:
GET http://www.api.apiato.develop/v1/cars?filter=id;name;status
GET http://www.api.apiato.develop/v1/cars/123?filter=id;name;status
-
获取属于汽车的所有驱动程序:
GET http://www.api.apiato.develop/v1/cars/123/drivers
GET http://www.api.apiato.develop/v1/cars/123/drivers/123/addresses
-
包含与汽车响应的驱动程序对象关系:
GET http://www.api.apiato.develop/v1/cars/123?include=drivers
GET http://www.api.apiato.develop/v1/cars/123?include=drivers,owner
-
添加新车:
POST http://www.api.apiato.develop/v1/cars
-
添加新的驱动程序到汽车:
POST http://www.api.apiato.develop/v1/cars/123/drivers
HTTP 方法的一般原则#
-
不要使用 GET 改变状态;防止 Googlebot 破坏您的数据。并尽可能使用 GET。
-
除非您要更新整个资源,否则请勿使用 PUT。除非你也可以在同一个 URI 上合法地进行 GET。
-
不要使用 POST 来检索长期存在或可能合理缓存的信息。
-
不要执行 PUT 不是幂等的操作。
-
除非输入很大,否则请使用 GET 进行计算等操作,在这种情况下使用 POST。
-
如有疑问,请优先使用 POST 而不是 PUT。
-
每当你必须做一些类似 RPC 的事情时,请使用 POST。
-
将 PUT 用于较大或分层的资源类。
-
使用 DELETE 优先于 POST 以删除资源。
本作品采用《CC 协议》,转载必须注明作者和本文链接
推荐文章: