1.使用名词而不是动词
分离了API结构和逻辑资源,通过Http方法GET, DELETE, POST 和 PUT来操作资源。
Resource GET POST PUT DELETE
/cars 返回cars集合 创建新的资源 批量更新cars 删除所有cars
/cars/711 返回特定的car 该方法不允许(405) 更新指定的资源 删除指定资源
不要使用:/getAllCars /createNewCar /deleteAllRedCars
2.Get方法和查询参数不应该涉及状态改变
使用PUT, POST 和DELETE 方法 而不是 GET 方法来改变状态,不要使用GET 进行状态改变:
GET /users/711?activate
GET /users/711/activate
3.使用复数名词
不要混淆名词单数和复数,为了保持简单,只对所有资源使用复数。
/cars 而不是 /car
/users 而不是 /user
/products 而不是 /product
/settings 而部署 /setting
4. 使用子资源表达关系
如果一个资源与另外一个资源有关系,使用子资源:
GET /cars/711/drivers/ 返回 car 711的所有司机
GET /cars/711/drivers/4 返回 car 711的4号司机
5.使用Http头声明序列化格式
在客户端和服务端,双方都要知道通讯的格式,格式在HTTP-Header中指定
Content-Type 定义请求格式
Accept 定义系列可接受的响应格式
6.使用超媒体作为应用状态的引擎,超文本链接可以建立更好的文本浏览:
{
"id": 711,
"manufacturer": "bmw",
"model": "X5",
"seats": 5,
"drivers": [
{
"id": "23",
"name": "Stefan Jauker",
"links": [
{
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}
注意href指向下一个URL
7.为集合提供过滤 排序 选择和分页等功能
Filtering过滤:
使用唯一的查询参数进行过滤:
GET /cars?color=red 返回红色的cars
GET /cars?seats<=2 返回小于两座位的cars集合
Sorting排序:
允许针对多个字段排序
GET /cars?sort=-manufactorer,+model
这是返回根据生产者降序和模型升序排列的car集合
Field selection
移动端能够显示其中一些字段,它们其实不需要一个资源的所有字段,给API消费者一个选择字段的能力,这会降低网络流量,提高API可用性。
GET /cars?fields=manufacturer,model,id,color
Paging分页
使用 limit 和offset.实现分页,缺省limit=20 和offset=0;
GET /cars?offset=10&limit=5
为了将总数发给客户端,使用订制的HTTP头: X-Total-Count.
链接到下一页或上一页可以在HTTP头的link规定,遵循Link规定:
Link: <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>; rel="next",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>; rel="last",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>; rel="first",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>; rel="prev",
8.版本化你的API
使得API版本变得强制性,不要发布无版本的API,使用简单数字,避免小数点如2.5.
一般在Url后面使用?v
/blog/api/v1
9. 使用Http状态码处理错误
如果你的API没有错误处理是很难的,只是返回500和出错堆栈不一定有用
Http状态码提供70个出错,我们只要使用10个左右:
200 – OK – 一切正常
201 – OK – 新的资源已经成功创建
204 – OK – 资源已经成功擅长
304 – Not Modified – 客户端使用缓存数据
400 – Bad Request – 请求无效,需要附加细节解释如 "JSON无效"
401 – Unauthorized – 请求需要用户验证
403 – Forbidden – 服务器已经理解了请求,但是拒绝服务或这种请求的访问是不允许的。
404 – Not found – 没有发现该资源
422 – Unprocessable Entity – 只有服务器不能处理实体时使用,比如图像不能被格式化,或者重要字段丢失。
500 – Internal Server Error – API开发者应该避免这种错误。
使用详细的错误包装错误:
{
"errors": [
{
"userMessage": "Sorry, the requested resource does not exist",
"internalMessage": "No car found in the database",
"code": 34,
"more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"
}
]
}
10.允许覆盖http方法
一些代理只支持POST 和 GET方法, 为了使用这些有限方法支持RESTful API,需要一种办法覆盖http原来的方法。
使用订制的HTTP头 X-HTTP-Method-Override 来覆盖POST 方法.
分享到:
相关推荐
这些REST的关键原则与将你的 API 分割成逻辑资源紧密相关。使用HTTP请求控制这些资源,其中,这些方法(GET, POST, PUT, PATCH, DELETE)具有特殊含义。 一旦定义好了资源, 需要确定什么样的 actions 应用它们,...
RESTful图书管理系统架构设计-restful api 设计最佳实践WORD范本.docx
目前互联网上充斥着大量的关于RESTfulAPI(为了方便,以后API和RESTfulAPI一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API格式如何?你的API是否应该加入版本信息?目前互联网上充斥着...
Roy Felding 在他论文 network based software architectures 的 第五章 中首次介绍了这些原则。这些REST的关键
restful api spring boot 简洁 资源
RESTful最佳实践之基于 jersey 的增删改查
动手的RESTful API设计模式和最佳实践 这是Packt发布的“ 的代码存储库。 设计,开发和部署高度适应性,可扩展性和安全性的RESTful Web API 这本书是关于什么的? 本书介绍了代表性状态传输(REST)范例,该范例...
RestfulAPI-s:使用最佳实践实现的RESTFul Web服务
Spring Boot API 项目种子是一个基于Spring Boot & MyBatis 的种子项目,用于快速构建中小型API、RESTful API 项目,该种子项目已经有过多个真实项目的实践,稳定、简单、快速,使我们摆脱困境这些劳动,专注于业务...
RESTful的Drupal最佳实践 该模块允许使用安全性,性能和可用性的最佳实践,通过RESTful HTTP请求来操作Drupal。 概念 以下是RESTful和其他模块(例如RestW和服务实体)之间的区别: RESTful需要明确声明公开的API。...
本白皮书的目的是了解创建 RESTful API 涉及哪些约束以及 Web REST API 的最佳实践是什么。 REST 约束 客户端服务器 无国籍 缓存 统一界面 分层系统 按需代码(可选) 客户端服务器 客户端-服务器约束侧重于关注点...
spring-rest-exception-handler, 一个方便的RESTful api Spring MVC 异常 spring REST异常处理程序 这个项目的目的是为for提供一个方便的异常处理程序( 解析器),它满足了错误响应的最佳实践。 处理自定义异常。...
Express / TypeScript / TypeORM RESTful API样板使用Express,TypeScript和TypeORM通过JWT身份验证和基于角色的授权构建RESTful API的最小样板,重点是最佳实践和无痛的开发人员经验。要求跑步克隆仓库npm run ...
其目标是提供一组声明性的接口,约定和最佳实践,以与各种数据源集成。 不仅是数据库-外部API,专有Web服务,甚至是硬件。 严格遵守适配器规范,可以(重新)使用内置的通用测试套件,标准化文档,对用户的API合理...
免责声明:本策略文档不是发明,而是代表了我们在网络上发现的最佳实践和见解的集合。 许多博客和论文为该策略中的内容提供了基础。 此策略中的建议只是“建议”。 背景 什么是API? 应用程序编程接口(API)是一...
Go Restful API样板库易于扩展的RESTful API样板库,旨在遵循惯用的Go和最佳实践。 该锅炉的目标是要有坚实的基础。 任何反馈和pu Go Restful API样板易于扩展的RESTful API样板,旨在遵循惯用的go和最佳实践。 该...
苯教胃口 内容 内容 部署方式 关于这个项目 此全栈餐厅跟踪和评论应用程序...遵循最佳实践 使用Vercel进行部署 Create React App入门 该项目是通过Create React App引导的。 可用脚本 在项目目录中,可以运行: n
编辑您的/etc/hosts文件以将 127.0.0.1 (localhost) 映射到开发域的 api 子域,如下所示: 127.0.0.1 localhost api.estate-dev.com 现在,启动 Rails 服务器,打开浏览器 ,您应该会看到 Rails 欢迎页面。 使用 ...