Restful规范

`Restful` 规范

1.`API`

API(Application Programming Interface):应用程序接口,是一些预先定义的函数, 或指软件系统不同组成部分衔接的约定.目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程(功能接口或服务的集合)的能力,而又无序访问源码,或解释内部工作机制的细节.

它类似于:

开发A研发了一个软件A,开发B 研发了一个软件B

如果开发A 在编写软件的过程中需要调用软件B 的一部分功能来完成,但是又不想看全部的软件B 的源码和功能实现过程.

这时,开发B 就把软件B 的部分功能打包,写成一个函数,并且约定好调用的方式和流程

开发A 就直接调用打包好的功能,就能实现需求,这部分打包好的功能就是API .

2.`Restful HTTP API` 规范

Restfun HTTP API 就是编写API 的一套规范.参照Github的编写规范,这里看比较重要的几点.

1.使用`HTTPS`

这个本身不是Restful API 的规定,但是对于增加网站的安全性非常重要,

note: 不要让非SSL 的URL 访问重定向到SSL URL.

2.`API` 地址和版本

在URL 中指定API 的版本是个很好的想法.如果API 变化比较大,可以把API 设置成子域名,比如https://developer.github.com/v3/ .也可以简单的把版本放在路径中,比如http://example.com/api/v1

3.`schema`

一个标准的URI
URI = scheme :// authority /path [ ?query ][ #fragment ]
对于响应返回的格式,JSON 因为它的可读性,紧凑性及多种语言的支持等优点,称为HTTP API 最常用的格式.因此,最好采用JSON 作为返回内容的格式.

4.`resource` 资源

resource 资源,也就是URL(Uniform Resource Locator) 路径,它是Restful API 的核心元素,所有的操作都是针对特定的资源进行的.所以简洁,清晰,结构化的URL 设计是至关重要的.

它大概包括:

根据RFC3986定义,URL是大小写敏感的.所以为了避免歧义,尽量使用小写字母.

不要使用动词,动词由HTTP 协议规定的Get/Post 等覆盖

URL 不要使用动词,应该使用名词,如果是多个,应该使用复数的形式.

单词之间使用下划线_ 来连接.

层级<= 3层,当大于3层时,应该使用? 查询字符串.
常见的情况是,resource 万网需要多级分类,因此很容易写出多级的URL.
Get /authors/test/categories/2
这种URL不利于扩展,语义不明确,应该使用查询字符串的形式表达
Get /authors/test/?category=2

5.`HTTP Method`

HTTP 规定的方法有:

HEAD 只获取某个资源的头部信息,比如只是获取某个文件的大小等

GET 从服务器上获取资源

POST 从服务器上新创建一个资源

PATCH 在服务器上更新资源,客户端需要提供需要改变的数据

PUT 在服务器上更新资源,客户端需要提供所有改变后的数据

DELETE 从服务器上删除资源

更常用的是GET/POST
GET /users/  获取所有用户
POST /users/  新建一个用户
PATCH /users/id/ 更新某个id的信息(只需要提供用户的更改信息)
PUT /users/id/ 更新某个id的信息(需要提供用户的所有信息)
DELETE /users/id/ 删除一个用户

`HEAD`	只获取某个资源的头部信息,比如只是获取某个文件的大小等
`GET`	从服务器上获取资源
`POST`	从服务器上新创建一个资源
`PATCH`	在服务器上更新资源,客户端需要提供需要改变的数据
`PUT`	在服务器上更新资源,客户端需要提供所有改变后的数据
`DELETE`	从服务器上删除资源

6.`HTTP` 状态码

常用的有

200 OK 服务器成功响应客户端的请求

400 INVILID REQUEST 用户发出的请求有误,服务器没有进行
新建或修改数据的操作

401 Unauthorized 用户没有权限访问这个请求

403 Forbidden 用户因为某些原因被禁止访问请求

404 NOT FOUND 用户请求的URL 不存在

406 NOT ACCEPTABLE 用户请求不被服务器接收(比如服务器期望客
户端发送某个字段,但是没有发送)

500 Internal server error 服务器内部错误

更多的状态码,点击访问

`200`	`OK`	服务器成功响应客户端的请求
`400`	`INVILID REQUEST`	用户发出的请求有误,服务器没有进行新建或修改数据的操作
`401`	`Unauthorized`	用户没有权限访问这个请求
`403`	`Forbidden`	用户因为某些原因被禁止访问请求
`404`	`NOT FOUND`	用户请求的`URL` 不存在
`406`	`NOT ACCEPTABLE`	用户请求不被服务器接收(比如服务器期望客户端发送某个字段,但是没有发送)
`500`	`Internal server error`	服务器内部错误