`
Tzhennan
  • 浏览: 57926 次
  • 性别: Icon_minigender_1
  • 来自: 上海
社区版块
存档分类
最新评论

rest/restful

 
阅读更多

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"

}

分享到:
评论

相关推荐

    REST开发者RESTful资源指南.rar

    维基百科把表述性状态转移(Representational State Transfer ,REST)定义为“分布式超媒体系统、如万维网的一种软件架构形式”... 潜在REST开发者的RESTful资源指南  REST:Web应用架构及基础设施的首选 ......

    REST开发者RESTful资源指南.docx

    2. **设计RESTful API**:API应遵循REST原则,提供清晰、一致的接口。这包括如何命名和组织资源,以及如何使用HTTP状态码有效地传达操作结果。 3. **使用HTTP首部和缓存**:HTTP首部可以用于传递元数据,如资源的...

    Delphi REST/HTTP POST Json示例

    在"RESTClient_main.dfm"和"RESTServer_main.dfm"文件中,分别定义了客户端和服务器的界面组件。客户端通常会包含一个RESTClient对象,用于发送请求,以及一个TStringGrid或类似的组件来展示响应结果。服务器端则...

    Spring Data REST简化RESTful开发.docx

    Spring Data REST 是基于 Spring Boot 和 Spring Data 项目构建 RESTful API 的强大工具,极大地简化了开发者的工作。在传统的 RESTful 开发中,我们需要手动编写控制器(Controller)来处理 HTTP 请求并映射到业务...

    REST_资源指南_restful.pdf

    总之,《REST开发者RESTful资源指南》是一份非常有价值的参考资料,无论是对于REST新手还是经验丰富的开发者来说,都能够从中获得宝贵的见解和实用的技巧。通过深入理解REST的核心理念和技术细节,开发者可以更加...

    ThunderStruck:RestJDBCCP更快的微服务

    REST / RESTful微服务 REST受Sinatra启发(无注释或配置) 多实例独立服务(简单的Jetty实现) 易于在容器(Tomcat,Glassfish,JBoss等)中使用 JDBC 特定的RDBMS ConnectionPool实现(实际上仅是HikariCP上的...

    Lazarus REST/JSON Server/Client Project-开源

    【Lazarus REST/JSON Server/Client Project-开源】是一个基于Lazarus的项目,它专注于实现RESTful服务和JSON数据交换。REST(Representational State Transfer)是一种软件架构风格,常用于构建分布式系统中的Web...

    rest-assured 为REST/HTTP服务提供方便测试的Java DSL

    Rest-Assured是一个用于测试RESTful Web服务的Java库。它提供了一组简单易用的API,可以方便地对HTTP请求和响应进行操作,包括发送GET、POST、PUT、DELETE等请求,以及验证HTTP状态码、响应头和响应体等

    Rest Restful 基于rocket服务搭建代码

    Rest Restful 基于rocket服务搭建代码 代码包含的实践用例: 1. restful post, get, put, delete方法 2. 基于rocket的中间层开发,用于日志处理 3. docker部署开发用的postgres 4. async 函数开发 5. async 函数递归...

    vREST API测试工具。「vREST - REST API Testing Tool」-crx插件

    此扩展是托管应用程序vREST(https://vrest.io-用于REST / RESTful / HTTP API的自动测试,模拟,自动记录的在线工具)的一部分。 这是一个非常简单的扩展,它记录了被测Web应用程序的HTTP请求,还记录了它们的参数...

    使用eclipse创建restful webservice 工程

    - 在浏览器中输入URL:`http://localhost:8080/RESTfulService/rest/hello`,如果一切正常,你应该能看到"Hello, World!"的响应。 至此,你已经成功地使用Eclipse创建了一个基本的RESTful Web服务工程。在实际开发...

    go-json-rest框架实现Golang Restful API项目的开发

    `go-json-rest`是一个轻量级且功能丰富的框架,专门设计用于快速构建RESTful APIs。本教程将深入探讨如何利用`go-json-rest`来实现一个用户管理的示例项目。 首先,`go-json-rest`框架的核心在于它提供了对HTTP请求...

    Spring CXF Restful 实例

    2. **创建RESTful服务接口**:定义Java接口,声明REST操作,如GET、POST方法。例如,我们可以创建一个名为`UserService`的接口,包含`getUser`和`saveUser`等方法。 3. **实现服务接口**:编写接口的实现类,如`...

    vREST - REST API Testing Tool-crx插件

    此扩展是托管应用程序vREST(https://vrest.io-用于REST / RESTful / HTTP API的自动测试,模拟,自动记录的在线工具)的一部分。 这是一个非常简单的扩展,它记录了受测Web应用程序的HTTP请求,还记录了它们的参数...

    什么是REST,符合REST的API叫RESTful 两种SOA接口实现:SOAP(WebService) vs REST

    RESTful API则是遵循REST原则的Web服务接口设计规范,它强调资源的表述和状态转移,使得系统更加简洁、高效。 在RESTful API的设计中,每个操作都对应于HTTP协议中的一个方法,如GET用于获取资源,POST用于创建资源...

    jcmdsbr:包含GitHub个人资料文档的存储库

    :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 REST实例

    使用Spring MVC3基于注解...4. 在浏览器中输入http://localhost:8080/restSpring/restful/new 检测页面是否能够被显示。 关于REST的详细说明,请参考blog http://blog.csdn.net/ziyifengfei/article/details/8185846

    RESTful的JavaScript开发包Rest.js.zip

    rest.js 是一个 RESTful HTTP 客户端的 JavaScript 包。 示例代码: var rest, mime, client; rest = require('rest'), mime = require('rest/interceptor/mime'); client = rest.chain(mime); client({ path: ...

    CAS restful接口调用

    <artifactId>cas-server-support-rest</artifactId> ${project.version}</version> </dependency> ``` 这里的`${project.version}`应当替换为你所使用的CAS版本号。添加完依赖后,需要重新构建项目或运行Maven...

    Delphi-Restful-Test-PHP

    REST(Representational State Transfer,表述性状态转移)是一种网络应用程序的设计风格和开发方式,基于HTTP协议,以资源为中心,通过URI(Uniform Resource Identifier)定位资源,通过HTTP方法(GET、POST、PUT...

Global site tag (gtag.js) - Google Analytics