REST,就是一种应用接口的设计风格。RESTful 是 REST 的形容词形式,RESTful API 指的是 REST 风格的接口。
一、协议
API与用户的通信协议,总是使用HTTPs协议
二、域名
应该尽量将API部署在专用域名之下。
https://api.example.com
如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。
https://example.org/api/
三、版本(Versioning)
应该将API的版本号放入URL。
https://api.example.com/v1/
另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。Github采用这种做法。
四、路径(Endpoint)
路径又称"终点"(endpoint),表示API的具体网址。
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
五、HTTP动词
对于资源的具体操作类型,由HTTP动词表示。
常用的HTTP动词有下面五个(括号里是对应的SQL命令)。
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
DELETE(DELETE):从服务器删除资源。
还有两个不常用的HTTP动词。
HEAD:获取资源的元数据。
OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。
例如:
GET /zoos:列出所有动物园
POST /zoos:新建一个动物园
GET /zoos/ID:获取某个指定动物园的信息
PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
DELETE /zoos/ID:删除某个动物园
GET /zoos/ID/animals:列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物
六、过滤信息(Filtering)
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
下面是一些常见的参数。
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件
七、状态码(Status Codes)
服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。
200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
八、错误处理(Error handling)
如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。
{
error: "Invalid API key"
}
相关推荐
维基百科把表述性状态转移(Representational State Transfer ,REST)定义为“分布式超媒体系统、如万维网的一种软件架构形式”... 潜在REST开发者的RESTful资源指南 REST:Web应用架构及基础设施的首选 ......
2. **设计RESTful API**:API应遵循REST原则,提供清晰、一致的接口。这包括如何命名和组织资源,以及如何使用HTTP状态码有效地传达操作结果。 3. **使用HTTP首部和缓存**:HTTP首部可以用于传递元数据,如资源的...
在"RESTClient_main.dfm"和"RESTServer_main.dfm"文件中,分别定义了客户端和服务器的界面组件。客户端通常会包含一个RESTClient对象,用于发送请求,以及一个TStringGrid或类似的组件来展示响应结果。服务器端则...
Spring Data REST 是基于 Spring Boot 和 Spring Data 项目构建 RESTful API 的强大工具,极大地简化了开发者的工作。在传统的 RESTful 开发中,我们需要手动编写控制器(Controller)来处理 HTTP 请求并映射到业务...
总之,《REST开发者RESTful资源指南》是一份非常有价值的参考资料,无论是对于REST新手还是经验丰富的开发者来说,都能够从中获得宝贵的见解和实用的技巧。通过深入理解REST的核心理念和技术细节,开发者可以更加...
REST / RESTful微服务 REST受Sinatra启发(无注释或配置) 多实例独立服务(简单的Jetty实现) 易于在容器(Tomcat,Glassfish,JBoss等)中使用 JDBC 特定的RDBMS ConnectionPool实现(实际上仅是HikariCP上的...
【Lazarus REST/JSON Server/Client Project-开源】是一个基于Lazarus的项目,它专注于实现RESTful服务和JSON数据交换。REST(Representational State Transfer)是一种软件架构风格,常用于构建分布式系统中的Web...
Rest-Assured是一个用于测试RESTful Web服务的Java库。它提供了一组简单易用的API,可以方便地对HTTP请求和响应进行操作,包括发送GET、POST、PUT、DELETE等请求,以及验证HTTP状态码、响应头和响应体等
Rest Restful 基于rocket服务搭建代码 代码包含的实践用例: 1. restful post, get, put, delete方法 2. 基于rocket的中间层开发,用于日志处理 3. docker部署开发用的postgres 4. async 函数开发 5. async 函数递归...
此扩展是托管应用程序vREST(https://vrest.io-用于REST / RESTful / HTTP API的自动测试,模拟,自动记录的在线工具)的一部分。 这是一个非常简单的扩展,它记录了被测Web应用程序的HTTP请求,还记录了它们的参数...
- 在浏览器中输入URL:`http://localhost:8080/RESTfulService/rest/hello`,如果一切正常,你应该能看到"Hello, World!"的响应。 至此,你已经成功地使用Eclipse创建了一个基本的RESTful Web服务工程。在实际开发...
`go-json-rest`是一个轻量级且功能丰富的框架,专门设计用于快速构建RESTful APIs。本教程将深入探讨如何利用`go-json-rest`来实现一个用户管理的示例项目。 首先,`go-json-rest`框架的核心在于它提供了对HTTP请求...
2. **创建RESTful服务接口**:定义Java接口,声明REST操作,如GET、POST方法。例如,我们可以创建一个名为`UserService`的接口,包含`getUser`和`saveUser`等方法。 3. **实现服务接口**:编写接口的实现类,如`...
此扩展是托管应用程序vREST(https://vrest.io-用于REST / RESTful / HTTP API的自动测试,模拟,自动记录的在线工具)的一部分。 这是一个非常简单的扩展,它记录了受测Web应用程序的HTTP请求,还记录了它们的参数...
RESTful API则是遵循REST原则的Web服务接口设计规范,它强调资源的表述和状态转移,使得系统更加简洁、高效。 在RESTful API的设计中,每个操作都对应于HTTP协议中的一个方法,如GET用于获取资源,POST用于创建资源...
:speech_balloon: Pergunte-me sobre REST / Restful,SOLID,DDD,Clean Code,DevOps,SistemasDistribuídos,Micro-serviçose Cultura Nerd :face_savoring_food: De 6的其他语言C#/。Net como语言主体和...
使用Spring MVC3基于注解...4. 在浏览器中输入http://localhost:8080/restSpring/restful/new 检测页面是否能够被显示。 关于REST的详细说明,请参考blog http://blog.csdn.net/ziyifengfei/article/details/8185846
rest.js 是一个 RESTful HTTP 客户端的 JavaScript 包。 示例代码: var rest, mime, client; rest = require('rest'), mime = require('rest/interceptor/mime'); client = rest.chain(mime); client({ path: ...
<artifactId>cas-server-support-rest</artifactId> ${project.version}</version> </dependency> ``` 这里的`${project.version}`应当替换为你所使用的CAS版本号。添加完依赖后,需要重新构建项目或运行Maven...
REST(Representational State Transfer,表述性状态转移)是一种网络应用程序的设计风格和开发方式,基于HTTP协议,以资源为中心,通过URI(Uniform Resource Identifier)定位资源,通过HTTP方法(GET、POST、PUT...