Restful后端API接口命名规范 |
您所在的位置：网站首页 › 接口用大驼峰命名吗 › Restful后端API接口命名规范 |
|
Restful 风格接口定义
一句话解释就是“通过路径知晓访问资源是何， 通过请求方式知道要做什么操作” 大致遵循以下两个规则： 请求 API 的 URL 表示用来定位资源； 请求的 METHOD 表示对这个资源进行的操作； 一. API的URL通过URL用来定位资源，跟要进行的操作区分开，这就意味着URL不该有任何动词 下面示例中的 get、create、search 等动词，都不应该出现在 REST 架构的后端接口路径中。比如：/api/getUser /api/createApp /api/searchResult /api/deleteAllUsers 当我们需要对单个用户进行操作时，根据操作的方式不同可能需要下面的这些接口：/api/getUser （用来获取某个用户的信息，还需要以参数方式传入用户 id 信息） /api/updateUser （用来更新用户信息） /api/deleteUser （用来删除单个用户） /api/resetUser （重置用户的信息） 可能在更新用户不同信息时，提供不同的接口，比如： /api/updateUserName /api/updateUserEmail /api/updateUser 正确的定义方式应该是 以上三种情况的弊端在于：首先加上了动词，肯定是使 URL 更长了；其次对一个资源实体进行不同的操作就是一个不同的 URL，造成 URL 过多难以管理。 其实当你回过头看“URL”这个术语的定义时，更能理解这一点。URL 的意思是统一资源定位符，这个术语已经清晰的表明，一个 URL 应该用来定位资源，而不应该掺入对操作行为的描述。 在 REST 架构的链接应该是这个样子： URL 中不应该出现任何表示操作的动词，链接只用于对应资源； URL 中应该单复数区分，推荐的实践是永远只用复数；比如GET /api/users表示获取用户的列表；如果获取单个资源，传入 ID，比如/api/users/123表示获取单个用户的信息； 按照资源的逻辑层级，对 URL 进行嵌套，比如一个用户属于某个团队，而这个团队也是众多团队之一；那么获取这个用户的接口可能是这样：GET /api/teams/123/members/234 表示获取 id 为 123 的小组下，id 为234 的成员信息。 按照类似的规则，可以写出如下的接口 /api/teams （对应团队列表） /api/teams/123 （对应 ID 为 123 的团队） /api/teams/123/members （对应 ID 为 123 的团队下的成员列表） /api/teams/123/members/456 （对应 ID 为 123 的团队下 ID 未 456 的成员） 二、API 请求的方法实际上，在HTTP请求中，我们不只有GET 和 POST 可用，在 REST 架构中，有以下几个重要的请求方法：GET，POST，PUT，DELETE。 顾名思义 【GET】 用于对某一(些)资源的‘获取’ 【POST】 用于对某一(些)资源进行‘创建’操作 【DELETE】 用于对某一(些)资源进行‘删除 ’ 【PUT】 用于对某一(些)资源进行‘更新’ 三、正确示例标准的格式是 http(s): //server.com /app-name /{version} /{domain} /{rest-convention}> {version}代表api的版本信息。 {domain}代表域名 （例如： localhost / 127.0.0.1） {rest-convention} 代表这个域(domain)下，你所访问的资源路径(约定的rest接口) 具体示例如下： 单资源( singular-resourceX ) url样例：order/ (order即指那个单独的资源X) GET – 返回一个新的order POST- 创建一个新的order，从post请求携带的内容获取值。 单资源带id(singular-resourceX/{id} ) URL样例：order/1 ( order即指那个单独的资源X ) GET – 返回id是1的order DELETE – 删除id是1的order PUT – 更新id是1的order，order的值从请求的内容体中获取。 复数资源(plural-resourceX/) URL样例:orders/ GET – 返回所有orders 复数资源查找(plural-resourceX/search) URL样例：orders/search?name=123 GET – 返回所有满足查询条件的order资源。(实例查询，无关联) – order名字等于123的。 复数资源查找(plural-resourceX/searchByXXX) URL样例：orders/searchByItems?name=ipad GET – 将返回所有满足自定义查询的orders – 获取所有与items名字是ipad相关联的orders。 单数资源(singular-resourceX/{id}/pluralY) URL样例：order/1/items/ (这里order即为资源X，items是复数资源Y) GET – 将返回所有与order id 是1关联的items。 singular-resourceX/{id}/singular-resourceY/ URL样例：order/1/item/ GET – 返回一个瞬时的新的与order id是1关联的item实例。 POST – 创建一个与order id 是1关联的item实例。Item的值从post请求体中获取。 singular-resourceX/{id}/singular-resourceY/{id}/singular-resourceZ/ URL样例：order/1/item/2/package/ GET – 返回一个瞬时的新的与item2和order1关联的package实例。 POST – 创建一个新的与item 2和order1关联的package实例，package的值从post请求体中获得。 总结几个关键点，来更清晰的表述规则。 在使用复数资源的时候，返回的是最后一个复数资源使用的实例。在使用单个资源的时候，返回的是最后一个单数资源使用的实例。查询的时候，返回的是最后一个复数实体使用的实例(们)。 一些其他规范： 规则1：URI结尾不应包含（/） 规则2：正斜杠分隔符（/）必须用来指示层级关系 规则3：应使用连字符（ - ）来提高URI的可读性 规则4：不得在URI中使用下划线（_） 规则5：URI路径中全都使用小写字母 |
| CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |