原文转自:https://bourgeois.me/rest/

REST APIs are a very common topic nowaday; they are part of almost every web application. A simple, consistent and pragmatic interface is a mandatory thing; it will be much easier for others to use your API. Even if these practices may look common to your eye, I often see people that don't really respect them. That's why I decided to write a post about it.

Here are some best practices to keep in mind while designing a RESTful API.

Discalmer: these best practices are what I think is good, based from my past expriences. If you think otherwise, feel free to send me an email so we can have a discussion about it.

Version your API

API versions should be mandatory. This way, you will be futureproof as the API changes through time. One way is to do is to pass the API version in the URL (/api/v1/...).

One other neat trick is to use the Accept HTTP header to pass the verison desired. Github does that.

Using versions will allow you to change the API structure without breaking compatibility with older clients.

Use nouns, not verbs

One thing I often see is people using verbs instead of nouns in their resources name. Here are some bad examples :

  • /getProducts
  • /listOrders
  • /retreiveClientByOrder?orderId=1

For a clean and conscice structure, you should always use nouns. Moreover, a good use of HTTP methods will allow you to remove actions from your resources names. Here is a much cleaner example :

  • GET /products : will return the list of all products
  • POST /products : will add a product to the collection
  • GET /products/4 : will retreive product #4
  • PATCH/PUT /products/4 : will update product #4

Use the plural form

In my opinion, it is not a really good idea to mix singular and plural forms in a single resource naming; it can quickly become confusing and non consistent.

Use /artists instead of /artist, even for the show/delete/update actions

GET and HEAD calls should always be safe

RFC2616 cleary states that HEAD and GET methods should always be safe to call (in other words, the state should not be altered).

Here is a bad example: GET /deleteProduct?id=1

Imagine a search engine indexing that page...

Use nested resources

If you want to get a sub collection (collection of an other one), use nested routing for a cleaner design. For instance, if you want to get a list of all albums of a particular artist, you would want to use :

  • GET /artists/8/albums

Paging

Returning a very large resultset over HTTP is not a very good idea neither. You will eventually run into performance issues as serializing a large JSON may quickly become expensive.

An option to get around that would be to paginate your results. Facebook, Twitter, Github, etc. does that. It is much more efficient to make more calls that takes little time to complete, than a big one that is very slow to execute.

Also, if you are using pagination, one good way to indicate the next and previous pages links is through the Link HTTP header. Github does that too.

Use proper HTTP status codes

Always use proper HTTP status codes when returning content (for both successful and error requests). Here a quick list of non common codes that you may want to use in your application.

Success codes

  • 201 Created should be used when creating content (INSERT),
  • 202 Accepted should be used when a request is queued for background processing (async tasks),
  • 204 No Content should be used when the request was properly executed but no content was returned (a good example would be when you delete something).

Client error codes

  • 400 Bad Request should be used when there was an error while processing the request payload (malformed JSON, for instance).
  • 401 Unauthorized should be used when a request is not authenticiated (wrong access token, or username or password).
  • 403 Forbidden should be used when the request is successfully authenticiated (see 401), but the action was forbidden.
  • 406 Not Acceptable should be used when the requested format is not available (for instance, when requesting an XML resource from a JSON only server).
  • 410 Gone Should be returned when the requested resource is permenantely deleted and will never be available again.
  • 422 Unprocesable entity Could be used when there was a validation error while creating an object.

A more complete list of status codes can be found in RFC2616.

Always return a consistent error payload

When an exception is raised, you should always return a consistent payload describing the error. This way, it will be easier for other to parse the error message (the structure will always be the same, whatever the error is).

Here one I often use in my web applications. It is clear, simple and self descriptive.

  1. HTTP/1.1 401 Unauthorized
  2. {
  3. "status": "Unauthorized",
  4. "message": "No access token provided.",
  5. "request_id": "594600f4-7eec-47ca-8012-02e7b89859ce"
  6. }

【转】最佳Restful API 实践的更多相关文章

  1. 基于Spring Boot的RESTful API实践(一)

    1. RESTful简述    REST是一种设计风格,是一组约束条件及原则,而遵循REST风格的架构就称为RESTful架构,资源是RESTful的核心,一个好的RESTful架构,通过URL就能很 ...

  2. 通俗易懂的RESTful API实践详解(含代码)

    来源:点击进入 点击上方链接,版面更好 一.什么是RESTful REST 是面向资源的,这个概念非常重要,而资源是通过 URI 进行暴露,URI 的设计只要负责把资源通过合理方式暴露出来就可以了,对 ...

  3. RESTful API实践总结

    REST架构 你是如何理解上网这件事的? 打开浏览器,输入网址,展现在你面前的就是一个网站了. 你可以在网站里看视频.看博客.写文章.听音乐. 但凡写过点代码的人都知道,我们平时访问的网站,其实是HT ...

  4. RESTful API 设计最佳实践

    背景 目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个"万能"的设计标准:如何鉴权?API ...

  5. [转]10个有关RESTful API良好设计的最佳实践

    Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的. 通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GE ...

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

    Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的. 通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GE ...

  7. ****RESTful API 设计最佳实践(APP后端API设计参考典范)

    http://blog.jobbole.com/41233/ 背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中“RESTful API ”简写为“API”)如何设计的文章,然而 ...

  8. RESTful API 设计最佳实践(转)

    摘要:目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API格式如何?你的API ...

  9. RESTful API 设计最佳实践(转)

    背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中“RESTful API ”简写为“API”)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API 格式如何?你的 ...

随机推荐

  1. visio个人专注

    字体颜色 1 填充 2 标注 3 箭头 4 线条 5 粗细 6

  2. C#中获取当前时间:System.DateTime.Now.ToString()用法

    //2008年4月24日 System.DateTime.Now.ToString("D"); //2008-4-24 System.DateTime.Now.ToString(& ...

  3. AndroidTouch事件总结

    1.自定义的控件几乎都要用到触摸事件,不交互怎么响应,相关的事件处理函数由dispatchTouchEvent.onInterceptTouchEvent.onTouchEvent,处理这些事件的由v ...

  4. css外边距margin

  5. Linux 文件访问权限

    定义:<sys/stat.h> 每个文件有9个访问权限,可将其分为3类: 标记 含义 S_IRUSR 用户读 S_IWUSR 用户写 S_IXUSR 用户执行 S_IRGRP 组读 S_I ...

  6. kendo模板 Uncaught Error: Invalid template:' 报错

    I was having a problem with a grid toolbar template because of a # in a hrefWorked out that I needed ...

  7. php foreach 语法的遍历来源数组如果不是一个有效数组php会出现错误警告 Invalid argument supplied for foreach()

    在php中,foreach语法的遍历来源数组如果不是一个有效数组,php会出现错误警告 Invalid argument supplied for foreach() ,但是很多时候这个数组是取自某些 ...

  8. LeetCode 177 Nth-Highest Salary mysql,取第n条数据,limit子句 难度:1

    https://leetcode.com/problems/nth-highest-salary/ ATTENTION:limit 子句只能接受int常量,不能接受运算式 CREATE FUNCTIO ...

  9. spring框架详解: IOC装配Bean

    1 Spring框架Bean实例化的方式: 提供了三种方式实例化Bean. 构造方法实例化:(默认无参数) 静态工厂实例化: 实例工厂实例化: 无参数构造方法的实例化: <!-- 默认情况下使用 ...

  10. Microsoft Azure Project Oxford 体验

    2015年4月29日,微软在Build 2015大会上发布了一个震撼人心的项目: Project Oxford, 可以帮助直接实现图像理解.人脸识别.语音识别.语音合成等功能.虽然说这是号称研究院的项 ...