RestfulAPI设计

RestfulAPI设计

1. 使用Https

这个和 Restful API 本身没有很大的关系，但是对于增加网站的安全是非常重要的。特别如果你提供的是公开 API，用户的信息泄露或者被攻击会严重影响网站的信誉。

2. API地址和版本

在 url 中指定 API 的版本是个很好地做法。如果 API 变化比较大，可以把 API 设计为子域名，比如 https://api.github.com/v3；也可以简单地把版本放在路径中，比如 https://example.com/api/v1

3.schema

对于响应返回的格式，JSON 因为它的可读性、紧凑性以及多种语言支持等优点，成为了 HTTP API 最常用的返回格式。因此，最好采用 JSON 作为返回内容的格式。如果用户需要其他格式，比如 xml，应该在请求头部 Accept 中指定。对于不支持的格式，服务端需要返回正确的 status code，并给出详细的说明。

4.以资源为中心的URL设计

资源是 Restful API 的核心元素，所有的操作都是针对特定资源进行的。而资源就是 URL（Uniform Resoure Locator）表示的，所以简洁、清晰、结构化的 URL 设计是至关重要的。Github 可以说是这方面的典范，下面我们就拿 repository 来说明。

/users/:username/repos
/users/:org/repos
/repos/:owner/:repo
/repos/:owner/:repo/tags
/repos/:owner/:repo/branchs/:branch

总结：

• 资源分为单个文档和集合，尽量使用复数来表示资源，单个资源通过添加 id 或者 name 等来表示
• 一个资源可以有多个不同的 URL
• 资源可以嵌套，通过类似目录路径的方式来表示，以体现它们之间的关系
• 根据RFC3986定义，URL是大小写敏感的。所以为了避免歧义，尽量使用小写字母

---

5. 使用正确的Method

有了资源的 URL 设计，所有针对资源的操作都是使用 HTTP 方法指定的。比较常用的方法有：

Method	描述
HEAD	只获取某个资源的头部信息。比如只想了解某个文件的大小，某个资源的修改日期等
GET	获取资源
POST	创建资源
PATCH	更新资源的部分属性。因为 PATCH 比较新，而且规范比较复杂，所以真正实现的比较少，一般都是用 POST 替代
PUT	替换资源，客户端需要提供新建资源的所有属性。如果新内容为空，要设置 Content-Length为 0，以区别错误信息
DELETE	删除资源

eg:

GET /repos/:owner/:repo/issues
GET /repos/:owner/:repo/issues/:number
POST /repos/:owner/:repo/issues
PATCH /repos/:owner/:repo/issues/:number
DELETE /repos/:owner/:repo

NOTE：更新和创建操作应该返回最新的资源，来通知用户资源的情况；删除资源一般不会返回内容。