• 在 RESTFul Api 的规则使用 HTTP 的方法
• Routes & Actions 命名约定
• RESTful url的一般准则和原则
• 好的URL示例
• HTTP方法的一般原则

在 RESTFul Api 的规则使用 HTTP 的方法

• GET (SELECT): 从服务器检索特定资源或资源列表。.
• POST (CREATE): 在服务器上创建一个新资源。
• PUT (UPDATE): 更新服务器上的资源，提供整个资源。
• PATCH (UPDATE): 更新服务器上的资源，只提供更改的属性。
• DELETE (DELETE):从服务器上删除资源。

Routes & Actions 命名约定

• GetAllResource: 获取所有资源。您可以应用?search查询参数来过滤数据。
• FindResourceByID: 通过唯一标识符搜索单个资源。
• CreateResource: 创建新资源。
• UpdateResource: 更新/编辑现有资源。
• DeleteResource: 删除资源。

RESTful url的一般准则和原则

• 一个 URL 标识资源。
• url应该包含名词，而不是动词。
• 只用复数名词表示一致性(不要用单数名词)。
• 使用HTTP谓词(GET、POST、PUT、DELETE)操作集合和元素。
• 你的字幕安不能比 resource/identifier/resource 更深
• 将版本号放在URL的底部, 例如 http://apiato.develop/v1/path/to/resource.
• 如果输入数据更改了端点的逻辑，应该在URL中传递它。如果没有，将数据放入头部，就像 Auth Token。
• 不要使用查询参数来更改状态。
• 如果可能，不要使用混合大小写路径;小写是最好的。
• 不要在url中使用特定于实现的扩展。（php、.py、.pl等)
• 尽可能限制URI空间。保持路径段短。
• 不要将元数据放在响应的主体中，而这些响应应该在标题中。

好的URL示例

• 通过唯一标识符(ID)找到一辆车:
  • 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
  • GEThttp://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来改变状态;防止Google蜘蛛损坏您的数据。尽可能多地使用GET。.
• 除非更新整个资源，否则不要使用PUT。除非您也可以合法地对同一个URI执行GET。
• 不要使用POST检索长期存在的信息，也不要使用POST缓存可能合理的信息。
• 不要对PUT执行非幂等的操作。
• 使用GET进行计算之类的工作，除非您的输入很大，在这种情况下使用POST。
• 当有疑问时，优先使用POST。
• 当你必须做一些感觉像rpc的事情时，使用POST。
• 对于较大或层次结构的资源类，请使用PUT。
• 使用DELETE而不是POST来删除资源。