blog/restful-info.md at master

5.7 KiB

Raw Permalink Blame History

title

date

什么是RestFul？

RestFul是在2000年由Roy Thomas Fielding博士在他的博士论文中提出。

他是http 1.0和1.1版本协议的主要设计者，apache基金会的第一任主席，可以说是现代互联网体系的奠基者。

Fielding将他对互联网软件的架构原则，定名为REST，即表述层状态转移（Representational State Transfer）。

这是一套在互联网体系下，调用者如何与被调用者（资源实体）进行互动的规范设计。

RestFul有什么样的规范？

在RestFul理论中，一个uri地址，指向一个资源对象。

设计

以不同的请求方式，来实现资源对象的不同操作。

GET ：从服务器取出资源（一项或多项）

POST ：在服务器新建一个资源

PUT ：在服务器更新资源（客户端提供改变后的完整资源）

PATCH ：在服务器更新资源（客户端提供改变的属性）

DELETE ：从服务器删除资源

例如：

有一个资源对象为user，1 是资源对象中的某一个对象中的唯一标识id。

GET 	/user：返回所有用户对象的列表（数组）
GET 	/user/resource：返回单个用户对象
POST 	/user：返回新生成的用户对象
PUT 	/user/resource：返回完整的用户对象
PATCH 	/user/resource：返回完整的用户对象
DELETE 	/user/resource：返回一个空文档

复数url

既然 URL 是名词，那么应该使用复数，还是单数？

这没有统一的规定，但是常见的操作是读取一个集合，比如GET /articles（读取所有文章），这里明显应该是复数。

为了统一起见，建议都使用复数 URL，比如GET /articles/2要好于GET /article/2。

避免多级URL

常见的情况是，资源需要多级分类，因此很容易写出多级的 URL，比如获取某个作者的某一类文章。

GET /authors/12/categories/2

这种 URL 不利于扩展，语义也不明确，往往要想一会，才能明白含义。

更好的做法是，除了第一级，其他级别都用查询字符串表达。

GET /authors/12?categories=2

下面是另一个例子，查询已发布的文章。你可能会设计成下面的 URL。

GET /articles/published

查询字符串的写法明显更好。

GET /articles?published=true

状态码

状态码必须精确

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。

HTTP 状态码就是一个三位数，分成五个类别。

1xx：相关信息 2xx：操作成功 3xx：重定向 4xx：客户端错误 5xx：服务器错误

这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。

每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就可以判断出发生了什么情况，

所以服务器应该返回尽可能精确的状态码。

API 不需要1xx状态码。

状态码详情可以看常见HTTP状态码

服务器响应

不要返回纯本文

API 返回的数据格式，不应该是纯文本，而应该是一个 JSON 对象，因为这样才能返回标准的结构化数据。

所以，服务器回应的 HTTP 头的Content-Type属性要设为application/json。

客户端请求时，也要明确告诉服务器，可以接受 JSON 格式，即请求的 HTTP 头的ACCEPT属性也要设成application/json。下面是一个例子。

GET /orders/2 HTTP/1.1 
Accept: application/json

发生错误时，不要返回 200 状态码

有一种不恰当的做法是，即使发生错误，也返回200状态码，把错误信息放在数据体里面，就像下面这样。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

上面代码中，解析数据体以后，才能得知操作失败。

这张做法实际上取消了状态码，这是完全不可取的。

正确的做法是，状态码反映发生的错误，具体的错误信息放在数据体里面返回。下面是一个例子。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}

提供链接

API 的使用者未必知道，URL 是怎么设计的。

一个解决方法就是，在回应中，给出相关链接，便于下一步操作。

这样的话，用户只要记住一个 URL，就可以发现其他的 URL。这种方法叫做 HATEOAS。

举例来说，GitHub 的 API 都在 api.github.com 这个域名。访问它，就可以得到其他 URL。

{
  ...
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  ...
}

上面的回应中，挑一个 URL 访问，又可以得到别的 URL。

对于用户来说，不需要记住 URL 设计，只要从 api.github.com 一步步查找就可以了。

HATEOAS 的格式没有统一规定，上面例子中，GitHub 将它们与其他属性放在一起。

更好的做法应该是，将相关链接与其他属性分开。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "In progress",
   "links": {[
    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
    { "rel":"edit", "method": "put", "href":"/api/status/12345" }
  ]}
}

原文链接：RESTful API 最佳实践

5.7 KiB Raw Permalink Blame History Unescape Escape