python restful api接口规范_restful api接口规范

简介：

REST：英文representational state transfer直译为表现层状态转移，或者表述性状态转移。

为什么需要Restful？

URL具有很强可读性的，具有自描述性

规范化请求过程和返回结果

资源描述与视图的松耦合

可提供OpenAPI，便于第三方系统集成，提高互操作性

提供无状态的服务接口，降低复杂度，可提高应用的水平扩展性

1、版本号

命名版本号可以解决版本不兼容问题，在设计 RESTful API 的一种实用的做法是使用版本号。一般情况下，我们会在 url 中保留旧版本号，并同时兼容多个版本

【GET】  /v1/users/{user_id}  // 版本 v1 的查询用户列表的 API 接口

【GET】  /v2/users/{user_id}  // 版本 v2 的查询用户列表的 API 接口

2、资源路径

URI 不能包含动词，只能是名词(命名名词的时候，要使用小写、数字及下划线来区分多个单词)。

资源的路径应该从根到子依次如下:

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

【POST】  /v1/users/{user_id}/roles/{role_id} // 添加用户的角色

有的时候，当一个资源变化难以使用标准的 RESTful API 来命名，可以考虑使用一些特殊的 actions 命名。

/{resources}/{resource_id}/actions/{action}