没有合适的资源？快使用搜索试试~ 我知道了~

首页RESTful API设计规范

RESTful API设计规范

REST

62 下载量 9 浏览量更新于2023-05-22 收藏 34KB DOCX 举报

身份认证购VIP最低享 7 折!

领优惠券(最高得80元）

试读

28页

RESTful架构应该遵循统一接口原则，统一接口包含了一组受限的预定义的操作，不论什么样的资源，都是通过使用相同的接口进行资源的访问。接口应该使用标准的HTTP方法如GET，PUT和POST，并遵循这些方法的语义。如果按照HTTP方法的语义来暴露资源，那么接口将会拥有安全性和幂等性的特性，例如GET和HEAD请求都是安全的，无论请求多少次，都不会改变服务器状态。而GET、HEAD、PUT和DELETE请求都是幂等的，无论对资源操作多少次，结果总是一样的，后面的请求并不会产生比第一次更多的影响。

资源详情

资源推荐

RESETful API 设计规范

为了避免歧义，文档大量使用了「能愿动词」，对应的解释如下：

 必须 (MUST)：绝对，严格遵循，请照做，无条件遵守；

 一定不可 (MUST NOT)：禁令，严令禁止；

 应该 (SHOULD)：强烈建议这样做，但是不强求；

 不该 (SHOULD NOT)：强烈不建议这样做，但是不强求；

 可以 (MAY)和可选 (OPTIONAL)：选择性高一点，在这个文档内，此词语使用较少；

参见：RFC 2119

协议

在通过 API于后端服务通信的过程中，应该使用 HTTPS协议。

API Root URL

API的根入口点应尽可能保持足够简单，这里有两个常见的 URL根例子：

 api.example.com/*

 example.com/api/*

如果你的应用很庞大或者你预计它将会变的很庞大，那应该将 API放到子域

下。这种做法可以保持某些规模化上的灵活性。

Versioning

所有的 API必须保持向后兼容，你必须在引入新版本 API的同时确保旧版

本 API仍然可用。所以应该为其提供版本支持。

目前比较常见的两种版本号形式：

在 URL 中嵌入版本编号

api.example.com/v1/*

这种做法是版本号直观、易于调试；另一种做法是，将版本号放在 HTTP

Header头中：

通过媒体类型来指定版本信息

Accept: application/vnd.example.com.v1+json

其中 vnd表示 Standards Tree标准树类型，有三个不同的树:x， prs

和 vnd。你使用的标准树需要取决于你开发的项目

prs

vnd

后面几个参数依次为应用名称（一般为应用域名）、版本号、期望的返回格

式。

至于具体把版本号放在什么地方，这个问题一直存在很大的争议，但由于我

们大多数时间都在使用 Laravel开发，应该使用 dingo/api来快速构建应用，

它采用第二种方式来管理 API版本，并且已集成了标准的 HTTP Response。

Endpoints

端点就是指向特定资源或资源集合的 URL。在端点的设计中，你必须遵守下

列约定：

 URL 的命名必须全部小写

 URL 中资源（ resource）的命名必须是名词，并且必须是复数形式

 必须优先使用 Restful类型的 URL

 URL 中不能出现 -，必须用下划线 _代替

 URL必须是易读的

 URL一定不可暴露服务器架构

来看一个反例

 https://api.example.com/getUserInfo?userid=1

 https://api.example.com/getusers

 https://api.example.com/sv/u

 https://api.example.com/cgi-bin/users/get_user.php?userid=1

再来看一个正列

 https://api.example.com/zoos

 https://api.example.com/animals

 https://api.example.com/zoos/{zoo}/animals

 https://api.example.com/animal_types

 https://api.example.com/employees

HTTP 动词

对于资源的具体操作类型，由 HTTP动词表示。常用的 HTTP动词有下面五个

（括号里是对应的 SQL命令）。

 GET（SELECT）：从服务器取出资源（一项或多项）。

 POST（CREATE）：在服务器新建一个资源。

 PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

 PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

 DELETE（DELETE）：从服务器删除资源。

其中

1 删除资源必须用 DELETE方法 2 创建新的资源必须使用 POST方法 3 更新

资源应该使用 PUT方法 4 获取资源信息必须使用 GET方法

针对每一个端点来说，下面列出所有可行的 HTTP动词和端点的组合

请求方法

URL

描述

GET /zoos

列出所有的动物园(ID 和名称，不要太详细)

请求方法

URL

描述

POST /zoos

新增一个新的动物园

GET /zoos/{zoo}

获取指定动物园详情

PUT /zoos/{zoo}

更新指定动物园(整个对象)

PATCH /zoos/{zoo}

更新动物园(部分对象)

DELETE /zoos/{zoo}

删除指定动物园

GET /zoos/{zoo}/animals

检索指定动物园下的动物列表(ID 和名称，不要太

详细)

GET /animals

列出所有动物(ID 和名称)。

POST /animals

新增新的动物

GET /animals/{animal}

获取指定的动物详情

PUT /animals/{animal}

更新指定的动物(整个对象)

PATCH /animals/{animal}

更新指定的动物(部分对象)

GET /animal_types

获取所有动物类型(ID 和名称，不要太详细)

GET /animal_types/{type}

获取指定的动物类型详情

剩余27页未读，继续阅读

粉丝: 2
资源: 18

上传资源快速赚钱

我的内容管理收起

我的资源快来上传第一个资源

我的收益

登录查看自己的收益

我的积分登录查看自己的积分

我的C币登录后查看C币余额

我的收藏

我的下载

下载帮助

会员权益专享

RESTful API设计规范

RESTful API接口通用完整规范_V1.doc

Restful web api

RESTFUL_API代码

restful api设计规范

restful api接口规范

RESTful API 的设计规范是什么

restful api 接口设计规范

restful api接口规范文档

简述WebApi中的restful api接口规范

restful api接口规范和服务调用的区别

python restful api接口规范

restful api接口开发规范

restful api接口规范 调用

java restful api接口规范

RESTful API技术都有哪些

什么是restful api

RESTful API

restful接口设计规范

RESTful API如何实现

RESTful api规范

会员权益专享

最新资源

restful api接口规范调用