RESTful Endpoint

Who invented REST?
REST was defined by Roy Fielding, a computer scientist. He presented the REST principles in his PhD dissertation in 2000.

REST 可以看成一种服务器接口设计的模式pattern。它的全称是 REpresentational State Transfer。它的意思就是说，服务器根据前端的请求，返回给可展示的资源状态。例如你请求了Weibo一个用户的信息，那么服务器就应该返回给你一个user，包含了姓名，账号，关注人数等信息。

相关名词

Resource：资源可以是前端想要获取的任何东西，一张图片，一个文件，一个用户的信息等等。
Collection：一系列的用户。
URL：Uniform Resource Locator，指向一个资源的路径。

为什么需要REST

如果在完全没有系统学习过接口设计的情况下，让你去设计一系列接口，你会怎么设计？我想大部分人都会做出如下的设计：

/addNewUser
/updateUser
/deleteUser
...

你或许会觉得这样的设计很readable啊，一看就知道是什么意思了。是的，可读性或许确实是它的一个优点，但同时不容易去维护你的接口。原因是你需要想方设法去像一个这种名字，接口少的时候还好，多了呢？如何解决接口重名的问题。
解决的方法就是舍弃这种依靠命名来分辨接口的办法。REST提出了一个很好的解决办法，依靠资源定位符和request方法来分辨要请求的资源以及要进行的操作（CRUD）。

Constraints in REST

1. 在 URL 中只能包含名词，不能包含动词，例如/addNewUser应该改成 /users。并且名词都是复数，不能是单数。这很好理解，资源在后台数据中都不是单个存在的，就像用户不可能只有一个一样。
2. 一个URL动作的定义取决于request的方法（GET，POST...）。具体请求方法对应的含义如下：
   a. GET 用来获取数据，并且不产生副作用(side effects)。例如 GET: /companies 应该获取所有的公司信息。
   b. POST 用来创建一个新的Resource。post不是一个幂等操作，也就是说多刺post操作会产生不一样的结果。就如同创建多个用户时，每一个用户都是不一样（起码id是不一样的）。
   所以使用 POST: /companies 会创建一个新的公司。
   c. PUT 用来更新一个资源，或者创建一个资源，如果不存在的话。
   所以 PUT: /companies/Amazon 会更新Amazon这家公司，或者先创建Amazon然后更新它。
   put是一个幂等操作，意味着多次相同URL的PUT操作只会产生一样的效果。就像更新一个用户，使用相同的信息就算更新一万次，结果也是一样的。
   d. DELETE 会从数据库删除该资源。

HTTP Response Status Code

2XX (Success category)

这类Code代表操作成功。

• 200 OK：标准的成功状态，一般适用于GET，PUT和POST。
• 201 Created：当新资源创建成功的时候可以返回这个状态。例如POST。
• 204 Not Content：代表操作成功，但没有需要返回的信息。例如DELETE，删除完成之后不需要返回额外信息了。

3xx (Redirection Category)

• 304 Not Modified indicates that the client has the response already in its cache. And hence there is no need to transfer the same data again.

4xx (Client Error Category)

These status codes represent that the client has raised a faulty request.

• 400 Bad Request indicates that the request by the client was not processed, as the server could not understand what the client is asking for.
• 401 Unauthorized indicates that the client is not allowed to access resources, and should re-request with the required credentials.
• 403 Forbidden indicates that the request is valid and the client is authenticated, but the client is not allowed access the page or resource for any reason. E.g sometimes the authorized client is not allowed to access the directory on the server.
• 404 Not Found indicates that the requested resource is not available now.
  410 Gone indicates that the requested resource is no longer available which has been intentionally moved.

5xx (Server Error Category)

• 500 Internal Server Error indicates that the request is valid, but the server is totally confused and the server is asked to serve some unexpected condition.
• 503 Service Unavailable indicates that the server is down or unavailable to receive and process the request. Mostly if the server is undergoing maintenance.