RESTful API 设计最佳实践

框架推荐： Resty

我所理解的REST, 直白点说就是直接利用HTTP协议, 并且尽量摒弃复杂冗余的东西(如cookie)的一个（API）设计风格。

由于直接利用了HTTP协议，你不需要“生搬硬照”出很多不常用不通用的方法，REST够简单，并且能够适应变化，支持任何一个可以处理HTTP协议的客户端。REST是一个风格, 没有一个明确的规范(比如RFC), 但是整个REST体系是十分健全和完善的.

REST的意思是表述性状态传递（Representational State Transferm）， 想要理解REST的设计思想，一定要看一看提出者Roy Fielding博士的论文，这个论文是有正式的中译版本的。

REST的典型应用是提供Web Service(API), 而且对于一些现代的Web应用来说, 仅仅是用一套Rest风格的APi, 就可以支持App, 浏览器, 以及对第三方提供API。在浏览器方面，结合AngularJs可以很好的实现单页应用。

另外值得一提的是， 作为一个程序员，更佳倾心于使用REST这种风格的设计， 优雅大气， 而且对于深入理解HTTP协议，设计Web API是有很大帮助的。

先说说基于SOAP的webservice。
客户端调用某个服务时，将方法、参数等信息按某种指定的结构包装，通过HTTP请求服务端。
服务端从报文解析出所需的信息并执行相应的方法，将结果按指定结构包装再响应给客户端。
REST确实不是SOAP的替代品，但这种方式被滥用了。
很多单纯靠HTTP就可以实现的功能却在HTTP上又加了一层奇怪的东西。

那说REST是一个什么好呢，毕竟它给人的印象并不严肃，而是更加清晰、简单。
就叫一个"原则"吧，符合这一原则便是RESTful。

• 资源：一个URL即作为一个实体的标识符，和客户端互动的就是这些资源。
• 表述：以什么方式展现给客户端，比如请求时用后缀名或者在Accept*中指定希望的展现方式。
• 状态：不仅是看看资源，我们也可以改变甚至创建资源，即状态转化。
  当然，这也仅通过HTTP，也就是Request Method：
  
  
  • GET:获取资源
  • POST:新建资源
  • PUT:更新资源
  • DELETE:删除资源

用URL表示资源，用动词表示如何操作资源。

不讓我複製我偏要複製 =͟͟͞͞( •̀д•́) 而且還偏要讓你看懂！！！！！！！

全部內容來自英文維基百科： http://en.wikipedia.org/wiki/Representational_state_transfer

Representational State Transfer

REST is an architecture style or design pattern used as a set of guidelines for creating web services which allow anything connected to a network (web servers, private intranets, smartphones, fitness bands, banking systems, traffic cameras, televisions etc.) to communicate with one another via a shared common communications protocol known as Hypertext Transfer Protocol (HTTP).

簡而言之，REST 就是基於 HTTP 通訊協議的一套架構風格或設計模式。

好了這已經足夠回答 REST 是啥了。那 RESTful 呢？-ful 就是把名詞變形容詞用的，所以：

The REST architectural style is also applied to the development of web services.[3] One can characterize web services as "RESTful" if they conform to the constraints described in the architectural constraints section.[4] RESTful web services are assumed to return data in XML and/or JSON format, the latter of which has been gaining more and more support and seems to be the data format of choice for many of the newer REST implementations.

RESTful 就是依 REST 架構開發 web 服務。好了我回答了 什麼是 RESTful。

等等，全是廢話！對啊，就是廢話。下面是場景：

Applied to web services

Web service APIs that adhere to the REST architectural constraints are called RESTful. HTTP based RESTful APIs are defined with these aspects:

• base URI, such as http://example.com/resources/
• an Internet media type for the data. This is often JSON but can be any other valid Internet media type (e.g. XML, Atom, microformats, images, etc.)
• standard HTTP methods (e.g., GET, PUT, POST, or DELETE)
• hypertext links to reference state
• hypertext links to reference related resources[10]
  The following table shows the HTTP methods that are typically used to implement a RESTful API.

簡單地說就是充分用上了 HTTP 協議的語義。

RESTful API HTTP methods

Resource	GET	PUT	POST	DELETE
Collection URI, such as http://example.com/resources/	List the URIs and perhaps other details of the collection's members.	Replace the entire collection with another collection.	Create a new entry in the collection. The new entry's URI is assigned automatically and is usually returned by the operation. [11]	Delete the entire collection.
Element URI, such as http://example.com/resources/item17	Retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type.	Replace the addressed member of the collection, or if it doesn't exist, create it.	Not generally used. Treat the addressed member as a collection in its own right and create a new entry in it. [11]	Delete the addressed member of the collection.

比如調用列表地址時（如 http://example.com/resources/ ），POST 是貼內容並返回內容地址。

調用內容地址時（如 http://example.com/resources/item17 ），PUT 創建內容，DELETE 刪除內容。

而 GET 都是 get 也就是獲取。

The PUT and DELETE methods are referred to as idempotent, meaning that the operation will produce the same result no matter how many times it is repeated. The GET method is a safe method (or nullipotent), meaning that calling it produces no side-effects. In other words, retrieving or accessing a record doesn't change it.

Unlike SOAP-based web services, there is no "official" standard for RESTful web APIs.[12] This is because REST is an architectural style, unlike SOAP, which is a protocol. Even though REST is not a standard per se, most RESTful implementations make use of standards like HTTP, URI, JSON, XML, etc.

理解這一段（冪等）需要數學基礎，不過簡而言之就是 PUT 和 DELETE 操作多次只有一次的副作用（還是不夠通俗哎）或者說成功操作的結果不依賴操作的次數。

舉例而言 POST 兩次就是兩個帖子，PUT 同一地址兩次（或更多）還是一個帖子。

以後遇到冪等這個詞，就想想這個例子好了。

練習題：帶有乘法運算的實數集當中有哪些冪等元素，不許百度（可以 Google）