`
HelloJimmy
  • 浏览: 35482 次
  • 性别: Icon_minigender_1
  • 来自: LostTemple
社区版块
存档分类
最新评论

10个有关RESTful API良好设计的最佳实践

    博客分类:
  • rest
阅读更多
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 方法.
分享到:
评论

相关推荐

    RESTful API 设计最佳实践

    RESTful API 设计最佳实践是构建可扩展、高效且易于使用的Web服务的关键。遵循REST(Representational State Transfer)原则,可以确保API与Web的核心概念——HTTP协议紧密结合,从而实现资源的透明操作。以下是对...

    C#中的RESTful API设计:最佳实践与实现指南

    本文将探讨C#中RESTful API设计的最佳实践,包括URL设计、状态码使用、版本控制、安全性考虑以及错误处理等方面。 设计和实现RESTful API是一个需要细致考虑的过程。遵循最佳实践,如使用合适的HTTP方法、状态码、...

    构建高效RESTful API:Golang最佳实践指南

    本文将探讨使用Golang开发RESTful API的最佳实践,包括设计原则、编码实践、安全性、性能优化等方面。 使用Golang开发RESTful API时,遵循最佳实践可以提高代码的可维护性、安全性和性能。从设计API开始,到编码、...

    RESTful API 设计最佳实践1

    RESTful API 设计最佳实践是构建高效、直观且易于使用的Web服务接口的关键。这一实践源自Roy Fielding在其论文“基于网络的软件架构”中的第五章,他提出了REST(Representational State Transfer)架构风格,用于...

    RESTFUL API设置最佳实

    ### RESTful API 设计最佳实践 #### 一、引言 随着互联网技术的发展,Web 应用变得越来越复杂,为了支持这些应用的功能扩展和服务交互,API 的设计变得尤为重要。RESTful API 是一种基于 HTTP 协议的应用程序编程...

    RESTful API设计规范

    以下是对RESTful API设计的一些关键规范和最佳实践的详细解读: #### 一、统一接口原则 - **概念**:RESTful架构的核心理念之一便是遵循统一接口的原则。这意味着,无论何种资源,都应通过一组有限预定义的操作来...

    restful API

    ### RESTful API 设计指南 随着信息技术的飞速发展,前端设备种类繁多,从前的单一桌面电脑到如今的智能手机、平板电脑以及其他...通过遵循这些原则和最佳实践,可以构建出高效、可靠且易于维护的RESTful API系统。

    C#中的RESTful API设计与实现

    通过遵循REST原则和最佳实践,你可以设计和实现强大、灵活且易于维护的API。在C#中,ASP.NET Core提供了一套完整的工具和框架来支持RESTful API的开发,使得从数据模型定义到控制器实现都变得简单直观。 在现代Web...

    RESTful API设计基础知识

    本文将深入探讨RESTful API设计的基础知识,包括其核心概念、原则和最佳实践。 REST(Representational State Transfer,表现层状态转移)是一种架构风格,源于Web的原始设计原则,由Roy Fielding在他的博士论文中...

    restful api guidelines

    RESTful API的设计主要遵循以下原则和最佳实践: 1. **资源导向**:RESTful API的核心是资源,每个URL代表一个资源,例如`/users/{userId}`表示用户资源。资源应使用名词,避免动词。 2. **HTTP方法**:使用HTTP...

    restful api 使用springboot简洁开发

    restful api spring boot 简洁 资源

    基于tp5的restfulapi风格接口oauth20接口版本管理

    综上所述,这个项目涉及了使用ThinkPHP5框架实现RESTful API接口,结合OAuth2.0进行安全授权,以及接口版本管理的最佳实践,对于想要学习和实践PHP Web服务开发的人员来说,是一个有价值的参考案例。通过深入理解...

    restful 接口开发规范(RESTfulAPIdesignguide)

    在开发RESTful接口时,我们需要遵循一定的设计规范来确保接口的一致性、可维护性和易用性。RESTful API(Representational State ...通过综合这些最佳实践和规范,我们可以构建出既强大又易于使用的RESTful API。

    基于 Go 语言构建企业级的 RESTful API 服务.pdf

    本文档全面介绍了如何利用 Go 语言构建企业级 RESTful API 服务,从开发环境的搭建、API 设计到开发、测试直至部署的全过程,涵盖了所有关键步骤和最佳实践。通过实战演练,不仅可以深入理解 RESTful API 的设计原理...

    Hands-On RESTful API Design Patterns and Best Practices

    本书的内容会涵盖RESTful API的设计模式和最佳实践,帮助开发者理解和掌握如何构建高效、安全、可靠的API服务。以下是书中可能涉及的几个关键知识点: 1. RESTful API设计原则:包括统一接口原则、无状态通信原则、...

    用flask写的一个restfulapi实例

    总结起来,本实例中的"用flask写的一个restfulapi实例"展示了如何利用Python的Flask框架创建一个RESTful API。通过学习这个实例,开发者能够掌握如何定义路由、处理HTTP方法、处理JSON数据、以及实现基本的认证机制...

Global site tag (gtag.js) - Google Analytics