REST API 设计学习笔记

RSET可以降低开发的复杂度，提高系统的可伸缩性，增强系统的可扩展性，简化系统之间的集成，因为得到广大开发人员的喜爱，也得到业界广泛的支持。




使用 POST 方法在服务器上创建资源

使用 PUT 方法对服务器的现有资源进行更新
使用 DELETE 方法删除服务器的某个资源


从一下几点来讨论rest api 设计

一 规划 资源表示结构 和 URL模式

1获取一个简单实体样例
REST API 请求： GET http://example.com/航班信息/CA827/entry

2 用feed 表示集合类型

3 url使用过滤条件，样例  / 环境工程系 / 学生 ?filter=age between (15, 18)

4 排序来帮助客户端更好的展现数据  样例 ?sortOrder=asc&sortField=age

5 分页展示数据 startIndex=27&count=22

二 根据应用场景提供内容协商
1 URL参数 进行内容协商 如，format=xml,format=json  协议版本
2 使用accept头对内容进行协商
通常使用 Accept 来设置我们接受的返回结果的内容格式，用 Accept-Charset 来设置字符集，用 Accept-Encoding 来设置数据传输格式，用 Accept-Language 来设置语言
3 用url 模式  航班号 /json 来返回 JSON 格式的结果

三 正确使用http相应代码


四 处理缓存和并发
缓存控制：
缓存控制通常是需要客户端，缓存服务器 / 代理服务器与业务服务器一起发生作用。
HTTP 头中有“Cache-control”字段来控制如何使用缓存，常见的取值有 private、no-cache、max-age、must-revalidate 等。比如当你给返回的数据内容设置 max-age=600，那么当用户隔了 30 秒再次请求的时候，就不会导致重新请求后台数据。
另外，也可以通过“Expires”字段来指定内容过期时间，在此时间前的请求都不会导致后台程序重新请求数据。

条件请求与电子标签：
很多时候，数据内容可能会几个小时甚至几天都不会发生变动，这个时候根据请求时间间隔来控制缓存，就不能满足系统的需求了。通过支持条件请求与电子标签，可以帮助我们来解决这个问题。
当用户请求数据内容时，系统在返回数据的同时，在 HTTP 头中，将返回根据服务器内容的最后修改时间 Last-Modified，或者根据服务器内容生成电子标签 ETag。 当用户再次请求数据时，就可以在 HTTP 请求中使用 If-Modified-Since 或者 If-None-Match 头信息，把上次请求得到的时间戳或者电子标签传给服务器。当收到一个有条件请求的 HTTP 头的 REST 请求的时候，我们的程序需要将收到的时间戳或者电子标签与当前内容作比较，就可以很容易的知道用户请求的数据内容在这段时间是否发生过修改，并根据比较结果返回给用户最新内容，或者用 HTTP 响应码 304 告知用户，内容没有变化。

并发处理：
通过在写操作中支持条件请求，我们可以更好的处理并发修改。用户在发出修改请求的同时，在 HTTP 请求中使用 If-Not-Modified-Since 或者 If-Match 头信息，把获取数据时得到的时间戳或者电子标签传给服务器；我们的程序通过与服务器当前内容的比较，就可以知道，这个修改请求是否是针对当前内容提出的。当服务器发现内容已经被其他用户修改过了，就不会执行修改请求，并返回 HTTP 响应码 412（未满足前提条件）给用户。

五 利用数据冗余和链接元素

数据结构中提供 其他api url 连控制冗余数据



其他技巧

批量更新：
当用户需要更新多个资源的时候，你打算让开发者一次次的发送 HTTP 请求逐个更新吗？你可以考虑在设计 API 的时候允许客户同时创建或者更新多个资源。

REST 安全：
除了使用固有的 HTTP 基本验证，你还可以考虑通过支持表单验证，LTPA 验证，Open ID 验证等方式，来满足更多的企业安全要求。

文档服务：
是否由于 API 持续更新，使得客户端连接不同版本服务的时候疲于奔命？尝试着把你的 API 定义规范成 XML 文档，这样客户端很容易理解当前服务可以提供哪些功能，以及如何使用这些功能。