REST API 完整形式

什么是RESTful API？

REST，即Representational State Transfer的缩写，表征性状态转移。是一种通信协议，而 RESTful 则是遵循REST风格设计的API接口。

RESTful API是一种无状态的API，不会在服务器端存储任何信息，而且可以被缓存，因此请求相同的资源时，服务器不用重复处理。RESTful API的各个资源通过HTTP协议中的GET、POST、PUT、DELETE方法与客户端进行交互，协议本身具有可扩展性、可组合性的特点。

RESTful API 完整形式

RESTful API的完整形式由以下四个部分组成：资源、请求方法、消息头、响应体。

资源

RESTful API的最基本概念是资源。API是基于资源的访问，因此资源是API的核心。资源可以是具体的数据对象，也可以是一个集合。比如，一个银行的API可以包括客户、银行账户、交易等资源。

每个资源都由URI（Uniform Resource Identifier）唯一标识，URI由协议、主机、端口和路径组成。例如，https://api.example.com/v1/customers/123/accounts/456就是表示资源的URI。

https://api.example.com/v1/customers/123/accounts/456

请求方法

在RESTful API中对资源的操作是通过HTTP请求方法来实现的。RESTful API主要支持四种请求方法：GET、POST、PUT、DELETE。

• GET：用于请求一个资源，不会对资源做出任何改变。请求成功将返回200 OK。
• POST：用于创建一个新资源或根据现有资源的情况执行操作。请求成功将返回201 Created。
• PUT：用于更新一个现有的资源。请求成功将返回204 No Content。
• DELETE：用于删除一个现有的资源。请求成功将返回204 No Content。

GET https://api.example.com/v1/customers/123/accounts/456
POST https://api.example.com/v1/customers/123/accounts
PUT https://api.example.com/v1/customers/123/accounts/456
DELETE https://api.example.com/v1/customers/123/accounts/456

消息头

HTTP消息头描述了请求或响应的内容，包括 MIME 类型、编码方式、请求者身份验证信息等。在RESTful API中，消息头中最常见的参数是Accept，Content-Type和Authorization。

• Accept：表示客户端期望服务器返回的数据类型，可以指定多个类型。例如：Accept: application/json, text/plain。
• Content-Type：表示请求或响应的主体中包含的数据类型。例如：Content-Type: application/json。
• Authorization：表示客户端的认证信息，可以是基础认证（Basic）或OAuth认证方式。

Accept: application/json, text/plain
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

响应体

RESTful API的响应体是服务器返回给客户端的数据，通常包括资源的数据表示。对于GET请求，响应体中一般包含请求到的资源的数据表示。

响应体中除了数据表示外，还包含HTTP状态码和可能的错误信息。常见的HTTP状态码包括：

• 200 OK：请求成功。
• 201 Created：请求成功，并且服务器创建了资源。
• 204 No Content：请求成功，但是响应中没有实体的主体部分。
• 400 Bad Request：请求失败，因为请求的语法无效。
• 401 Unauthorized：请求失败，因为客户端没有通过身份验证。
• 404 Not Found：请求失败，因为请求的资源无效或不存在。
• 500 Internal Server Error：服务器发生意外错误。

响应体的数据格式一般是JSON或XML。使用JSON的优势是易于阅读和解析，使用XML的优势是具有良好的扩展性和可读性。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 456,
  "name": "Savings Account",
  "balance": 1000
}

总结

本文介绍了RESTful API的完整形式，包括资源、请求方法、消息头和响应体。RESTful API是一种基于HTTP协议的可扩展、可组合的API风格，并且适合于分布式系统和云计算环境。设计好的RESTful API可以提高系统的可靠性、可用性和扩展性。