RESTful API 接口设计指南

已于 2023-11-30 10:09:16 修改
阅读量1.3k 收藏 18
点赞数 22
分类专栏： 编程开发 文章标签： restful RESTful API 状态码 Http 响应码
于 2023-11-30 09:57:31 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/mrluo735/article/details/134689396
版权

目录

一. 前言

二. RESTful API 设计的定义

2.1. 重要术语

2.2. 一般规范

2.3. 协议

2.4. 域名

2.5. 版本（Version）

2.6. Http 动词

2.7. 路径（Endpoint）

2.8. 过滤（Filter）

2.9. 返回结果

2.10. 错误处理

三. Hypermedia API

四. 状态码（Http 响应码）

4.1. 状态码范围

4.2. 状态码大全

一. 前言

    网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他终端设备等）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现“API First”的设计思想。RESTful API 是目前比较成熟的一套互联网应用程序的 API 设计理论。

    REST（Representational State Transfer）表述性状态转换，REST 指的是一组架构约束条件和原则。 如果一个架构符合 REST 的约束条件和原则，我们就称它为 RESTful 架构。REST 本身并没有创造新的技术、组件或服务，而隐藏在 RESTful 背后的理念就是使用 Web 的现有特征和能力， 更好地使用现有 Web 标准中的一些准则和约束。虽然 REST 本身受 Web 技术的影响很深， 但是理论上 REST 架构风格并不是绑定在 HTTP 上，只不过目前 HTTP 是唯一与 REST 相关的实例。

    RESTful 是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。 基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

二. RESTful API 设计的定义

2.1. 重要术语

以下是我将贯穿在整个文档中的几个重要的术语：

资源：一个对象的单个实例。比如，一个动物。
集合：一个同类型对象的集合。比如，动物们。
HTTP：网络通信协议。
消费者：能够发生 HTTP 请求的客户端应用程序。
第三方开发者：不属于你项目组成员但是希望使用你数据的开发者。
服务：一个 HTTP 服务/应用能够通过网络被消费者访问。
节点：服务器上的 API URL ，它能代表资源或整个集合。
幂等性：无副作用，可以多次发生而没有副作用。
URL 段：URL 中由斜杠(“/”)分隔的信息段。

2.2. 一般规范

1. 不用大写；
2. 用中杠 -，不用下划线 _;
3. 参数列表要 encode；
4. URI 中的名词表示资源集合，使用复数形式；
5. URI 表示资源的两种方式：资源集合、单个资源
    5.1. 资源集合
    /zoos                // 所有动物园
    /zoos/1/animals    // id为1的动物园中的所有动物
    5.2. 单个资源
    /zoos/1            // id为1的动物园
    /zoos/1;2;3        // id为1、2、3的动物园
6. 避免层级过深的URI
    / 在 URL 中表达层级，用于按实体关联关系进行对象导航，一般根据 id 导航。
    过深的导航容易导致 URL 膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4，尽量使用查询参数代替路径中的实体导航，如 GET /animals?zoo=1&area=3。
7. 对组合资源的访问
    服务器端的组合实体必须在 URI 中通过父实体的 id 导航访问。
    组合实体不是 first-class 的实体，它的生命周期完全依赖父实体，无法独立存在，在实现上通常是对数据库表中某些列的抽象，不直接对应表，也无 id。一个常见的例子是 User — Address，Address 是对 User 表中 zipCode、country、city 三个字段的简单抽象，无法独立于 User 存在。必须通过 User 索引到 Address：GET /user/1/addresses。

2.3. 协议

API与用户的通信协议，包含 http 和 https，总是使用HTTPs协议可以确保交互数据的传输安全。

2.4. 域名

应该尽量将API部署在专用域名之下：

https://api.example.com

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下：

https://example.org/api/

2.5. 版本（Version）

应该将API的版本号放入URL：

https://api.example.com/v1/

另一种做法是，将版本号放在 HTTP 头信息中，但不如放入 URL 方便和直观。Github 采用这种做法。

2.6. Http 动词

对于资源的具体操作类型，由 HTTP 动词表示。

常用的 HTTP 动词如下表：

请求方式对应SQL安全性幂等性说明
GETSELECT是是从服务器取出资源（一项或多项）
POSTINSERT、CREATE否否在服务器新建一个资源。
PUTUPDATE否是在服务器更新资源（客户端提供改变后的完整资源）。
PATCHUPDATE否是在服务器更新资源（客户端提供改变的属性）。
DELETEDELETE否是从服务器删除资源。
HEAD是是获取资源的元数据。
OPTIONS是是获取信息，关于资源的哪些属性是客户端可以改变的。

2.7. 路径（Endpoint）

路径又称“终点”（endpoint），表示API的具体网址。

在 RESTful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表名对应。一般来说，数据库中的表都是同种记录的“集合”（collection），所以API中的名词也应该使用复数。

举例来说，有一个 API 提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样：

路径请求方式说明
https://api.example.com/v1/zoosGET列出所有动物园 (id、name等信息)
https://api.example.com/v1/zoosPOST创建一个新的动物园
https://api.example.com/v1/zoos/{zId}GET获取一个动物园详情
https://api.example.com/v1/zoos/{zId}PUT更新指定动物园（全量数据更新）
https://api.example.com/v1/zoos/{zId}PATCH更新指定动物园（部分数据更新）
https://api.example.com/v1/zoos/{zId}DELETE删除指定动物园
https://api.example.com/v1/zoos/{zId}/animalsGET列出某个指定动物园下的所有动物

https://api.example.com/v1/zoos/{zId}/animals

/{aId}

DELETE删除某个指定动物园的指定动物
https://api.example.com/v1/animalsGET列出所有动物（id、name等信息）
https://api.example.com/v1/animalsPOST创建一个新的动物
https://api.example.com/v1/animals/{aId}GET获取指定动物详情
https://api.example.com/v1/animals/{aId}PUT更新指定动物（全量数据更新）
https://api.example.com/v1/animals/{aId}PATCH更新指定动物（部分数据更新）
https://api.example.com/v1/animal_typesGET列出动物类型（id、name等信息）
https://api.example.com/v1/animal_types/{atId}GET获取指定的动物类型
https://api.example.com/v1/employeesGET列出所有雇员列表（id、name等信息）
https://api.example.com/v1/employees/{eId}GET获取指定雇员详情
https://api.example.com/v1/zoos/{zId}/employeesGET获取指定动物园下的雇员列表
https://api.example.com/v1/employeesPOST创建一个新的雇员
https://api.example.com/v1/zoos/{zId}/employeesPOST为指定动物园聘请一个雇员

https://api.example.com/v1/zoos/{zId}

/employees/{eId}

DELETE删除指定动物园下的指定雇员

2.8. 过滤（Filter）

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。参数的设计允许存在冗余，即允许 API 路径和 URL 参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

下面是一些常见的参数：

Query参数说明
?limit=10指定返回记录的数量
?offset=10指定返回记录的开始位置。
?page=2&page_size=100指定第几页，以及每页的记录数。
?sortby=name&order=asc指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type=dog指定筛选条件

2.9. 返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范：

资源URI请求方式返回结果

/collection

如：/zoos

GET返回资源对象的列表（数组）
/collection/resource

如：/zoos/{zId}

GET返回单个资源对象

/collection

如：/zoos

POST返回新生成的资源对象
/collection/resource

如：/zoos/{zId}

PUT返回完整的资源对象
/collection/resource

如：/zoos/{zId}

PATCH返回完整的资源对象
/collection/resource

如：/zoos/{zId}

DELETE返回一个空文档

2.10. 错误处理

如果状态码是 4xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可。

{
    error: "Invalid API key"
}

三. Hypermedia API

    RESTful API 最好做到 Hypermedia，即返回结果中提供链接，连向其他 API 方法，使得用户不查文档，也知道下一步应该做什么。

比如，当用户向 api.example.com 的根目录发出请求，会得到这样一个文档：

{
  "link": {
    "rel":   "collection https://www.example.com/zoos",
    "href":  "https://api.example.com/zoos",
    "title": "List of zoos",
    "type":  "application/vnd.yourformat+json"
  }
}

上面代码表示，文档中有一个 link 属性，用户读取这个属性就知道下一步该调用什么 API 了。rel表示这个 API 与当前网址的关系（collection 关系，并给出该 collection 的网址），href 表示 API的路径，title 表示 API 的标题，type 表示返回类型。

Hypermedia API 的设计被称为 HATEOAS。Github 的 API 就是这种设计，访问 api.github.com 会得到一个所有可用 API 的网址列表：

{
  "current_user_url": "https://api.github.com/user",
  "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}",
  "authorizations_url": "https://api.github.com/authorizations",
  "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}",
  "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}",
  "emails_url": "https://api.github.com/user/emails",
  "emojis_url": "https://api.github.com/emojis",
  "events_url": "https://api.github.com/events",
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}",
  "issues_url": "https://api.github.com/issues",
  "keys_url": "https://api.github.com/user/keys",
  "label_search_url": "https://api.github.com/search/labels?q={query}&repository_id={repository_id}{&page,per_page}",
  "notifications_url": "https://api.github.com/notifications",
  "organization_url": "https://api.github.com/orgs/{org}",
  "organization_repositories_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}",
  "organization_teams_url": "https://api.github.com/orgs/{org}/teams",
  "public_gists_url": "https://api.github.com/gists/public",
  "rate_limit_url": "https://api.github.com/rate_limit",
  "repository_url": "https://api.github.com/repos/{owner}/{repo}",
  "repository_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}",
  "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}",
  "starred_url": "https://api.github.com/user/starred{/owner}{/repo}",
  "starred_gists_url": "https://api.github.com/gists/starred",
  "topic_search_url": "https://api.github.com/search/topics?q={query}{&page,per_page}",
  "user_url": "https://api.github.com/users/{user}",
  "user_organizations_url": "https://api.github.com/user/orgs",
  "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}",
  "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}"
}

从上面可以看到，如果想获取当前用户的信息，应该去访问 api.github.com/user，然后就得到了下面结果：

{
  "message": "Requires authentication",
  "documentation_url": "https://docs.github.com/rest/users/users#get-the-authenticated-user"
}

上面代码表示，服务器给出了提示信息，以及文档的网址。

四. 状态码（Http 响应码）

4.1. 状态码范围

1xx 范围的状态码是保留给底层 HTTP 功能使用的，并且估计在你的职业生涯里面也用不着手动发送这样一个状态码出来。

2xx 范围的状态码是保留给成功消息使用的，你尽可能的确保服务器总发送这些状态码给用户。

3xx 范围的状态码是保留给重定向用的。大多数的 API 不会太常使用这类状态码，但是在新的超媒体样式的 API 中会使用更多一些。

4xx 范围的状态码是保留给客户端错误用的。例如，客户端提供了一些错误的数据或请求了不存在的内容。这些请求应该是幂等的，不会改变任何服务器的状态。

5xx 范围的状态码是保留给服务器端错误用的。这些错误常常是从底层的函数抛出来的，并且开发人员也通常没法处理。发送这类状态码的目的是确保客户端能得到一些响应。收到 5xx 响应后，客户端没办法知道服务器端的状态，所以这类状态码是要尽可能的避免。

4.2. 状态码大全

Code 码名称含义
1 字头，消息 Informational
100Continue客户端应当继续发送请求。 这个临时响应是用来通知客户端它的部分请求已经被服务器接收，且仍未被拒绝。客户端应当继续发送请求的剩余部分，或者如果请求已经完成，忽略这个响应。 服务器必须在请求完成后向客户端发送一个最终响应。
101Switching Protocols

    服务器已经理解了客户端的请求，并将通过Upgrade消息头通知客户端采用不同的协议来完成这个请求。在发送完这个响应最后的空行后，服务器将会切换到在Upgrade消息头中定义的那些协议。

    只有在切换新的协议更有好处的时候才应该采取类似措施。例如，切换到新的HTTP版本比旧版本更有优势，或者切换到一个实时且同步的协议以传送利用此类特性的资源。

102Processing代表处理将被继续执行。由WebDAV（RFC 2518）扩展的状态码
2 字头， 成功 Success
200OK请求已成功，请求所希望的响应头或数据体将随此响应返回。
201Created请求已经被实现，而且有一个新的资源已经依据请求的需要而建立，且其 URI 已经随Location头信息返回。假如需要的资源无法及时建立的话，应当返回 '202 Accepted'。
202Accepted

    服务器已接受请求，但尚未处理。正如它可能被拒绝一样，最终该请求可能会也可能不会被执行。在异步操作的场合下，没有比发送这个状态码更方便的做法了。

    返回202状态码的响应的目的是允许服务器接受其他过程的请求（例如某个每天只执行一次的基于批处理的操作），而不必让客户端一直保持与服务器的连接直到批处理操作全部完成。在接受请求处理并返回202状态码的响应应当在返回的实体中包含一些指示处理当前状态的信息，以及指向处理状态监视器或状态预测的指针，以便用户能够估计操作是否已经完成。

203Non-Authoritative Information服务器已成功处理了请求，但返回的实体头部元信息不是在原始服务器上有效的确定集合，而是来自本地或者第三方的拷贝。当前的信息可能是原始版本的子集或者超集。例如，包含资源的元数据可能导致原始服务器知道元信息的超集。使用此状态码不是必须的，而且只有在响应不使用此状态码便会返回200 OK的情况下才是合适的。
204No Content

    服务器成功处理了请求，但不需要返回任何实体内容，并且希望返回更新了的元信息。响应可能通过实体头部的形式，返回新的或更新后的元信息。如果存在这些头部信息，则应当与所请求的变量相呼应。

    如果客户端是浏览器的话，那么用户浏览器应保留发送了该请求的页面，而不产生任何文档视图上的变化，即使按照规范新的或更新后的元信息应当被应用到用户浏览器活动视图中的文档。

    由于204响应被禁止包含任何消息体，因此它始终以消息头后的第一个空行结尾。

205Reset Content

    服务器成功处理了请求，且没有返回任何内容。但是与204响应不同，返回此状态码的响应要求请求者重置文档视图。该响应主要是被用于接受用户输入后，立即重置表单，以便用户能够轻松地开始另一次输入。

    与204响应一样，该响应也被禁止包含任何消息体，且以消息头后的第一个空行结束。

206Partial Content

    服务器已经成功处理了部分 GET 请求。类似于 FlashGet 或者迅雷这类的HTTP下载工具都是使用此类响应实现断点续传或者将一个大文档分解为多个下载段同时下载。

    该请求必须包含 Range 头信息来指示客户端希望得到的内容范围，并且可能包含 If-Range 来作为请求条件。

207Multi-Status代表之后的消息体将是一个XML消息，并且可能依照之前子请求数量的不同，包含一系列独立的响应代码。由WebDAV(RFC 2518)扩展的状态码
208Already Reported一次绑定的成员已经在前一部分列举（Multi-Status）的反应，并没有被再次列入。由WebDAV(RFC 5842)扩展的状态码
209IM Used服务器已经完成了对资源的请求，响应是应用于当前实例的一个或多个实例操作的结果的表示。由WebDAV(RFC 3229)扩展的状态码
3 字头，重定向 Redirection
300Multiple Choices

    被请求的资源有一系列可供选择的回馈信息，每个都有自己特定的地址和浏览器驱动的商议信息。用户或浏览器能够自行选择一个首选的地址进行重定向。

    除非这是一个 HEAD 请求，否则该响应应当包括一个资源特性及地址的列表的实体，以便用户或浏览器从中选择最合适的重定向地址。这个实体的格式由Content-Type 定义的格式所决定。浏览器可能根据响应的格式以及浏览器自身能力，自动作出最合适的选择。当然，RFC2616规范并没有规定这样的自动选择该如何进行。

    如果服务器本身已经有了首选的回馈选择，那么在 Location 中应当指明这个回馈的 URI；浏览器可能会将这个 Location值作为自动重定向的地址。此外，除非额外指定，否则这个响应也是可缓存的。

301Moved Permanently

    被请求的资源已永久移动到新位置，并且将来任何对此资源的引用都应该使用本响应返回的若干个 URI 之一。如果可能，拥有链接编辑功能的客户端应当自动把请求的地址修改为从服务器反馈回来的地址。除非额外指定，否则这个响应也是可缓存的。

    新的永久性的URI 应当在响应的 Location 域中返回。除非这是一个 HEAD 请求，否则响应的实体中应当包含指向新的 URI 的超链接及简短说明。

    如果这不是一个 GET 或者 HEAD 请求，因此浏览器禁止自动进行重定向，除非得到用户的确认，因为请求的条件可能因此发生变化。

    注意：对于某些使用 HTTP/1.0 协议的浏览器，当它们发送的 POST 请求得到了一个301响应的话，接下来的重定向请求将会变成 GET方式。

302Move temporarily

    请求的资源临时从不同的URI响应请求。由于这样的重定向是临时的，客户端应当继续向原有地址发送以后的请求。只有在Cache-Control或Expires中进行了指定的情况下，这个响应才是可缓存的。        如果这不是一个 GET 或者 HEAD 请求，那么浏览器禁止自动进行重定向，除非得到用户的确认，因为请求的条件可能因此发生变化。

    注意：虽然RFC 1945和RFC 2068规范不允许客户端在重定向时改变请求的方法，但是很多现存的浏览器将302响应视作为303响应，并且使用 GET 方式访问在 Location 中规定的 URI，而无视原先请求的方法。状态码303和307被添加了进来，用以明确服务器期待客户端进行何种反应。

303See Other

    对应当前请求的响应可以在另一个 URI 上被找到，而且客户端应当采用 GET 的方式访问那个资源。这个方法的存在主要是为了允许由脚本激活的POST请求输出重定向到一个新的资源。这个新的 URI 不是原始资源的替代引用。同时，303响应禁止被缓存。当然，第二个请求（重定向）可能被缓存。

    注意：许多 HTTP/1.1 版以前的浏览器不能正确理解303状态。如果需要考虑与这些浏览器之间的互动，302状态码应该可以胜任，因为大多数的浏览器处理302响应时的方式恰恰就是上述规范要求客户端处理303响应时应当做的。

304Not Modified如果客户端发送了一个带条件的 GET 请求且该请求已被允许，而文档的内容（自上次访问以来或者根据请求的条件）并没有改变，则服务器应当返回这个状态码。304响应禁止包含消息体，因此始终以消息头后的第一个空行结尾。
305Use Proxy

被请求的资源必须通过指定的代理才能被访问。Location 域中将给出指定的代理所在的 URI 信息，接收者需要重复发送一个单独的请求，通过这个代理才能访问相应资源。只有原始服务器才能建立305响应。

    注意：RFC 2068中没有明确305响应是为了重定向一个单独的请求，而且只能被原始服务器建立。忽视这些限制可能导致严重的安全后果。

306Switch Proxy

    请求的资源临时从不同的URI 响应请求。

    新的临时性的URI 应当在响应的 Location 域中返回。除非这是一个HEAD 请求，否则响应的实体中应当包含指向新的 URI 的超链接及简短说明。因为部分浏览器不能识别307响应，因此需要添加上述必要信息以便用户能够理解并向新的 URI 发出访问请求。

    如果这不是一个GET 或者 HEAD 请求，那么浏览器禁止自动进行重定向，除非得到用户的确认，因为请求的条件可能因此发生变化。

307Temporary Redirect在这种情况下，应该用另一个URI重复请求，但是，将来的请求仍然应该使用原来的URI。相反，有302是历史上实施，请求的方法是不允许被改变时，补发原来的要求。例如，应使用另一个POST请求重复POST请求。
308Permanent Redirect应使用另一个URI重复请求和所有未来请求。307和308并行302和301的行为，但不允许HTTP方法更改。因此，例如，向永久重定向资源提交表单可能会继续顺利进行。由WebDAV(RFC 7538)扩展的状态码
4 字头，请求错误 Client Errors
400Bad Request

1、语义有误，当前请求无法被服务器理解。除非进行修改，否则客户端不应该重复提交这个请求。

2、请求参数有误。

401Unauthorized当前请求需要用户验证。该响应必须包含一个适用于被请求资源的 WWW-Authenticate 信息头用以询问用户信息。客户端可以重复提交一个包含恰当的 Authorization 头信息的请求。如果当前请求已经包含了 Authorization 证书，那么401响应代表着服务器验证已经拒绝了那些证书。如果401响应包含了与前一个响应相同的身份验证询问，且浏览器已经至少尝试了一次验证，那么浏览器应当向用户展示响应中包含的实体信息，因为这个实体信息中可能包含了相关诊断信息。参见RFC 2617。
402Payment Required该状态码是为了将来可能的需求而预留的。
403Forbidden服务器已经理解请求，但是拒绝执行它。与401响应不同的是，身份验证并不能提供任何帮助，而且这个请求也不应该被重复提交。如果这不是一个 HEAD 请求，而且服务器希望能够讲清楚为何请求不能被执行，那么就应该在实体内描述拒绝的原因。当然服务器也可以返回一个404响应，假如它不希望让客户端获得任何信息。
404Not Found

    请求失败，请求所希望得到的资源未被在服务器上发现。没有信息能够告诉用户这个状况到底是暂时的还是永久的。假如服务器知道情况的话，应当使用410状态码来告知旧资源因为某些内部的配置机制问题，已经永久的不可用，而且没有任何可以跳转的地址。

    404这个状态码被广泛应用于当服务器不想揭示到底为何请求被拒绝或者没有其他适合的响应可用的情况下。

    出现这个错误的最有可能的原因是服务器端没有这个页面。

405Method Not Allowed

    请求行中指定的请求方法不能被用于请求相应的资源。该响应必须返回一个 Allow 头信息用以表示出当前资源能够接受的请求方法的列表。

    鉴于 PUT，DELETE 方法会对服务器上的资源进行写操作，因而绝大部分的网页服务器都不支持或者在默认配置下不允许上述请求方法，对于此类请求均会返回405错误。

406Not Acceptable

    请求的资源的内容特性无法满足请求头中的条件，因而无法生成响应实体。

    除非这是一个 HEAD 请求，否则该响应就应当返回一个包含可以让用户或者浏览器从中选择最合适的实体特性以及地址列表的实体。实体的格式由 Content-Type 头中定义的媒体类型决定。浏览器可以根据格式及自身能力自行作出最佳选择。但是，规范中并没有定义任何作出此类自动选择的标准。

407Proxy Authentication Required与401响应类似，只不过客户端必须在代理服务器上进行身份验证。代理服务器必须返回一个 Proxy-Authenticate 用以进行身份询问。客户端可以返回一个 Proxy-Authorization 信息头用以验证。参见RFC 2617。
408Request Timeout请求超时。客户端没有在服务器预备等待的时间内完成一个请求的发送。客户端可以随时再次提交这一请求而无需进行任何更改。
409Conflict

    由于和被请求的资源的当前状态之间存在冲突，请求无法完成。这个代码只允许用在这样的情况下才能被使用：用户被认为能够解决冲突，并且会重新提交新的请求。该响应应当包含足够的信息以便用户发现冲突的源头。

    冲突通常发生于对 PUT 请求的处理中。例如，在采用版本检查的环境下，某次 PUT 提交的对特定资源的修改请求所附带的版本信息与之前的某个（第三方）请求向冲突，那么此时服务器就应该返回一个409错误，告知用户请求无法完成。此时，响应实体中很可能会包含两个冲突版本之间的差异比较，以便用户重新提交归并以后的新版本。

410Gone

    被请求的资源在服务器上已经不再可用，而且没有任何已知的转发地址。这样的状况应当被认为是永久性的。如果可能，拥有链接编辑功能的客户端应当在获得用户许可后删除所有指向这个地址的引用。如果服务器不知道或者无法确定这个状况是否是永久的，那么就应该使用404状态码。除非额外说明，否则这个响应是可缓存的。

    410响应的目的主要是帮助网站管理员维护网站，通知用户该资源已经不再可用，并且服务器拥有者希望所有指向这个资源的远端连接也被删除。这类事件在限时、增值服务中很普遍。同样，410响应也被用于通知客户端在当前服务器站点上，原本属于某个个人的资源已经不再可用。当然，是否需要把所有永久不可用的资源标记为'410 Gone'，以及是否需要保持此标记多长时间，完全取决于服务器拥有者。

411Length Required服务器拒绝在没有定义 Content-Length 头的情况下接受请求。在添加了表明请求消息体长度的有效 Content-Length 头之后，客户端可以再次提交该请求。
412Precondition Failed服务器在验证在请求的头字段中给出先决条件时，没能满足其中的一个或多个。这个状态码允许客户端在获取资源时在请求的元信息（请求头字段数据）中设置先决条件，以此避免该请求方法被应用到其希望的内容以外的资源上。
413Request Entity Too Large

    服务器拒绝处理当前请求，因为该请求提交的实体数据大小超过了服务器愿意或者能够处理的范围。此种情况下，服务器可以关闭连接以免客户端继续发送此请求。

    如果这个状况是临时的，服务器应当返回一个 Retry-After 的响应头，以告知客户端可以在多少时间以后重新尝试。

414Request-URI Too Long

    请求的URI 长度超过了服务器能够解释的长度，因此服务器拒绝对该请求提供服务。这比较少见，通常的情况包括：

    本应使用POST方法的表单提交变成了GET方法，导致查询字符串（Query String）过长。

    重定向URI “黑洞”，例如每次重定向把旧的 URI 作为新的 URI 的一部分，导致在若干次重定向后 URI 超长。

    客户端正在尝试利用某些服务器中存在的安全漏洞攻击服务器。这类服务器使用固定长度的缓冲读取或操作请求的 URI，当 GET 后的参数超过某个数值后，可能会产生缓冲区溢出，导致任意代码被执行[1]。没有此类漏洞的服务器，应当返回414状态码。

415Unsupported Media Type对于当前请求的方法和所请求的资源，请求中提交的实体并不是服务器中所支持的格式，因此请求被拒绝。
416Requested Range Not Satisfiable

    如果请求中包含了 Range 请求头，并且 Range 中指定的任何数据范围都与当前资源的可用范围不重合，同时请求中又没有定义 If-Range 请求头，那么服务器就应当返回416状态码。

    假如 Range 使用的是字节范围，那么这种情况就是指请求指定的所有数据范围的首字节位置都超过了当前资源的长度。服务器也应当在返回416状态码的同时，包含一个 Content-Range 实体头，用以指明当前资源的长度。这个响应也被禁止使用 multipart/byteranges 作为其 Content-Type。

417Expectation Failed在请求头 Expect 中指定的预期内容无法被服务器满足，或者这个服务器是一个代理服务器，它有明显的证据证明在当前路由的下一个节点上，Expect 的内容无法被满足。
418I'm a teapot这个代码在1998被定义为传统的IETF四月愚人节的笑话之一，在RFC 2324，Hyper Text Coffee Pot Control Protocol，预计不会被实际的HTTP服务器实现。
419Insufficient Space On Resource资源空间不足
421Misdirected Request请求指向不能生成响应的服务器（例如，因为连接重用）。
422Unprocessable Entity请求格式正确，但是由于含有语义错误，无法响应。
423Locked当前资源被锁定。
424Failed Dependency由于之前的某个请求发生的错误，导致当前请求失败，例如 PROPPATCH。
425Unordered Collection无序的集合。在WebDav Advanced Collections 草案中定义，但是未出现在《WebDAV 顺序集协议》（RFC 3658）中。
426Upgrade Required客户端应当切换到TLS/1.0。
428Precondition Required源服务器要求请求是有条件的。为了防止“丢失更新”问题，客户机获取资源状态，修改资源，并将其返回到服务器，同时，第三方修改了服务器上的状态，导致冲突。
429Too Many Requests用户在给定的时间内发送了太多请求。
431Request Header Fields Too Large服务器不愿意处理请求，因为单个头字段或所有头字段都是太大了。
451Unavailable For Legal Reasons该请求因法律原因不可用。
5 字头 服务器错误 Server error
500Internal Server Error服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理。一般来说，这个问题都会在服务器端的源代码出现错误时出现。
501Not Implemented服务器不支持当前请求所需要的某个功能。当服务器无法识别请求的方法，并且无法支持其对任何资源的请求。
502Bad Gateway作为网关或者代理工作的服务器尝试执行请求时，从上游服务器接收到无效的响应。
503Service Unavailable

    由于临时的服务器维护或者过载，服务器当前无法处理请求。这个状况是临时的，并且将在一段时间以后恢复。如果能够预计延迟时间，那么响应中可以包含一个 Retry-After 头用以标明这个延迟时间。如果没有给出这个 Retry-After 信息，那么客户端应当以处理500响应的方式处理它。

    注意：503状态码的存在并不意味着服务器在过载的时候必须使用它。某些服务器只不过是希望拒绝客户端的连接。

504Gateway Timeout

    作为网关或者代理工作的服务器尝试执行请求时，未能及时从上游服务器（URI标识出的服务器，例如HTTP、FTP、LDAP）或者辅助服务器（例如DNS）收到响应。

    注意：某些代理服务器在DNS查询超时时会返回400或者500错误

505HTTP Version Not Supported服务器不支持，或者拒绝支持在请求中使用的 HTTP 版本。这暗示着服务器不能或不愿使用与客户端相同的版本。响应中应当包含一个描述了为何版本不被支持以及服务器支持哪些协议的实体。
506Variant Also Negotiates由《透明内容协商协议》（RFC 2295）扩展，代表服务器存在内部配置错误：被请求的协商变元资源被配置为在透明内容协商中使用自己，因此在一个协商处理中不是一个合适的重点。
507Insufficient Storage服务器无法存储完成请求所必须的内容。这个状况被认为是临时的。WebDAV (RFC 4918)
508Loop Detected服务器在处理请求时检测到了一个无限循环(sent in lieu of 208 Already Reported)。
510Not Extended获取资源所需要的策略并没有没满足。（RFC 2774）
511Network Authentication Required客户端需要进行身份验证才能获得网络访问权限。意在通过截取代理来控制对网络的访问（例如，“门户网站”用于在通过Wi-Fi热点提供全面Internet接入之前要求协议服务条款）
非官方状态码
103Checkpoint用于恢复请求建议恢复中止PUT或POST请求
103Early Hints用于在整个HTTP响应之前返回一些响应头
420Method Failure一个废弃的响应使Spring框架一个方法失败了
420Enhance Your Calm当客户机受到限制时，由Twitter搜索和趋势API的版本1返回，版本1.1和以后使用429个请求响应代码代替
450Blocked by Windows Parental Controls微软扩展代码指示Windows父母控件打开并阻止对给定网页的访问。
498Invalid Token表示已过期或无效的令牌。
499Token Required表示需要令牌，但未提交令牌。
509Bandwidth Limit Exceeded服务器已经超出了服务器管理员指定的带宽；这通常被共享主机提供商用来限制用户的带宽。
530Site is frozen用于指示由于不活动而被冻结的站点。
598Network read timeout error某些HTTP代理用于在代理后面向代理客户机发出网络读取信号超时。
599Network connect timeout error用于指示连接到网络超时。
600Unparseable Response Headers源站没有返回响应头部，只返回实体内容
Internet Information Services(IIS)状态码
440Internet Information Services客户端会话已过期，必须再次登录。
449Retry With由微软扩展，代表请求应当在执行完适当的操作后进行重试。
451Redirect

    使用Exchange ActiveSync时更有效的可用的服务器或服务器无法访问用户的邮箱。

    客户有望重新运行HTTP自动发现运行找到更合适的服务器。

Nginx 状态码
444No Response用于指示服务器没有向客户端返回任何信息并关闭连接。
495SSL Certificate Error当客户端提供无效客户端证书时使用的400 Bad Request响应代码的扩展
496SSL Certificate Required扩展400 Bad Request响应代码，当需要客户端证书但不提供时使用。
497HTTP Request Sent to HTTPS Port当客户机对侦听HTTPS请求的端口发出HTTP请求时使用的400 Bad Request响应代码的扩展。
499Client Closed Request在客户端在服务器发送响应之前关闭请求时使用。
Cloudflare 状态码
520Unknown Error520错误用作“当原始服务器返回意外事件时的catch响应”，作为常见触发器，列出连接重置、大标题和空或无效响应。
521Web Server Is Down源服务器拒绝连接
522Connection Timed Out不能与源服务器进行TCP握手。
523Origin Is Unreachable无法到达源服务器；例如，如果原始服务器的DNS记录不正确。
524A Timeout Occurred能够完成对源服务器的TCP连接，但没有及时收到HTTP响应。
525SSL Handshake Failed无法与源服务器协商SSL / TLS握手。
526Invalid SSL Certificate无法验证源服务器呈现的SSL / TLS证书。
527Railgun Error错误527表示WAN连接后请求超时或失败。

流华追梦
关注
  • 22
    点赞
  • 踩
  • 18
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
专栏目录
微软REST API的指南-python
06-18
为了在遵循 Microsoft REST API 指南的平台上为开发人员提供尽可能流畅的体验，REST API 应遵循一致的设计指南，以使其使用简单直观。 行为准则 该项目采用了微软开源行为准则。 有关更多信息，请参阅行为准则...
军用软件接口设计规范
12-23
军用软件接口设计规范，有详细的接口设计文档模板
什么是RESTful API?
热门推荐
Evan's Blog ٩(๑❛ᴗ❛๑)۶
12-25 8万+
        提到RESTful API 大家势必或多或少听说过。但是什么是RESTful API ？如何理解RESTful API 呢？请大家耐心读完这篇文章，相信您读完后一定会有一个更好的理解。我个人认为，要弄清楚什么是RESTful API,首先要弄清楚什么是REST。REST 全称：REpresentational State Transfer，英文翻译过来就是“表现层状态转化”。如果...
RESTful API介绍
D1842501760的博客
04-06 2533
文章目录RESTful API查看源图像什么是API?什么是RESTful API?解读REST(了解内容)RESTful API 规范信息过滤状态码（Status Codes）RESTful 的极致 HATEOAS-END- RESTful API 正式学习RESTful API之前,我们需要把什么是API搞懂. 什么是API? API（Application Programming Interface） 翻译过来是应用程序编程接口的意思。 相信大家对于API这个此已经不陌生了, 比如"我调用了某某的A
什么是RESTful API? 详解@ResponseBody @RequestBosy @PathVariable@RestController
无限进步
03-07 1200
@RequestMapping @RequestMapping 是一个Spring MVC注解，用于定义HTTP请求的映射规则。 在RESTful API中，每个资源都对应一个URL路径，而HTTP方法则表示对资源的操作类型。例如，对于一个用户资源的API，我们可能需要定义一个URL路径为 /users，并使用GET、POST、PUT、DELETE等HTTP方法来对用户资源进行操作。
RESTfulAPI详解
一个优秀的极客「白泽」
02-20 1万+
1. 什么是RESTfulAPI RESTful API 是一种互联网软件架构的设计规范，设计指南，设计风格，设计原则（类似于web标准，并不是标准【规范，原则】） 2. 产生背景 开始开发时，前后端高度融合（耦合） 近些年：前后端分离，前端各种客户端产生。基于这种现状，需要一个统一的机制。为前后端通信服务（API机制） 因此，前后端分离开来前后端基于API 开发，即：面向接口开发 前后端基于接口传递数据。 RESTfulAPI作为制定接口标准的规范而产生了。 3. RESTful API API简介：
Restful风格API
qq_45726570的博客
03-04 2784
一、什么是API？ API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。——百度百科 简单来说就是：别人写好代码，编译号程序，可以让其他人调用使用，就称作API。你使用了别人代码（或者程序）中的某个函数、类、对象，就叫做使用了某个API。 二、restful是什么？ restful是一种软件架构风格、设计风格，而..
RESTful API
weixin_46591816的博客
03-08 761
RESTful API
Microsoft REST API准则-Python开发
05-24
Microsoft REST API指南Microsoft REST API指南作为一种设计原则，鼓励应用程序开发人员通过RESTful HTTP接口访问资源。 为了提供尽可能流畅的体验Microsoft REST API准则Microsoft REST API准则是Microsoft内部公司...
Java毕业设计-基于springboot开发的致远汽车租赁系统--论文-附毕设源代码+说明文档.rar
03-08
在技术上，该系统采用了前后端分离的开发模式，前端使用现代的前端框架，后端则基于Spring Boot构建RESTful API。数据库方面，系统使用了关系型数据库进行数据存储和管理，确保了数据的完整性和一致性。此外，系统还...
计算机专业毕业设计-微信小程序案例-微信小程序的美甲店铺座位预约系统NodeJS-毕设源码+说明文档.rar
最新发布
03-09
- API接口：提供RESTful风格的API接口，方便前端调用。 **文档内容：** - 系统需求分析 - 技术选型与架构设计 - 数据库设计与实现 - 后端API接口详细说明 - 小程序前端代码结构与实现 - 项目部署与运行指南 - 二次...
RESTful API接口基本内容
keavykk的博客
04-09 3107
RESTful API接口基本内容 目录 RESTful API接口基本内容 一、RESTful是什么？ 1.1.基本特点 1.2.设计概念和准则 1.3.http协议 二、RESTful与SOAP WebService 架构有什么区别？ 2.1.WebService 架构概念 2.2.两者对比 三、如何实现符合RESTful规范的API？ 3.1.资源路径（URI） 3....
详解 restful API
weixin_53156345的博客
05-15 1668
​ 服务器不能保存客户端的信息，每一次从客户端发送的请求中，要包含所有必须的状态信息，会话信息由客户端保存，服务器端根据这些状态信息来处理请求，当客户端可以切换到一个新状态的时候发送请求信息，当一个或者多个请求被发送之后，客户端就处于一个状态变迁过程中。从请求方式上无法知道API是干嘛的，素有在URL上都会有操作的动词来表示API进行的动作，例如：query，add，update，delete等等。安全性是指：方法不会修改资源状态，朗读的为安全的，写的操作为非安全的。
Restful API 的接口规范
zhoupenghui168的博客
02-11 1万+
发展背景及简介 网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。 rest是Representational State Transfer三个单词的缩写，由Roy Fielding于2000年论文中提出的一种web软件结构风格，注意它仅仅只是代表着一种风格，并不代表着约束、标准。基
Restful API接口
weixin_43956958的博客
07-04 3201
非Rest设计，以往我们都会这么写： http://localhost:8080/admin/getUser （查询用户） http://localhost:8080/admin/addUser （新增用户） http://localhost:8080/admin/updateUser （更新用户） http://localhost:8080/admin/deleteUser （删除用户） 总结：以不同的URL（主要为使用动词）进行不同的操作。 Rest架构： GET http://localhost:80
RESTful API 概述
叁木大数据
03-11 3024
RESTful API 是一种基于 REST 架构风格设计的 Web API。而在讲其之前我们应该先去聊聊REST，。而RESTful API 通常基于 HTTP 协议进行通信，通过 URI（Uniform Resource Identifier，统一资源标识符）指定资源的位置，通过 HTTP 方法（GET、POST、PUT、DELETE 等）操作资源，通过 HTTP 状态码表示请求的处理结果。
restful api 接口设计规范
11-30
RESTful API 是一种基于 HTTP 协议，通过 URI、HTTP 动词、HTTP 报文等方式来实现资源的增删改查等操作的一种 API 设计规范。其设计原则包括客户端-服务器、无状态、可缓存、统一接口等。具体来说，RESTful API 的设计应该遵循以下几个方面： 1. URI 设计：URI 应该清晰、简洁、易于理解，且应该使用名词而非动词来表示资源。 2. HTTP 动词：HTTP 动词应该与资源的操作相对应，例如 GET 方法用于获取资源，POST 方法用于创建资源等。 3. HTTP 报文：HTTP 报文应该包含足够的信息来描述资源的操作，例如请求头中的 Accept 字段用于指定客户端接受的数据类型，响应头中的 Content-Type 字段用于指定服务器返回的数据类型等。 4. 资源的表现形式：资源应该以多种不同的表现形式呈现，例如 JSON、XML 等。 5. 超媒体：超媒体是 RESTful API 的一个重要特性，它通过在响应中包含链接来描述资源之间的关系，从而使客户端能够自动发现和访问相关资源。 以下是一个示例： 假设我们要设计一个 RESTful API 来管理用户信息，我们可以按照以下方式设计 URI： - 获取所有用户信息：GET /users - 获取指定用户信息：GET /users/{id} - 创建用户信息：POST /users - 更新指定用户信息：PUT /users/{id} 删除指定用户信息：DELETE /users/{id} 其中，{id} 表示用户的唯一标识符。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

流华追梦

你的鼓励将是我创作最大的动力。

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值