restful api
URL是说白了,就是一个句子,其中资源是名词,HTTP方法是动词。
GET 方法从资源请求数据,不应产生任何其他作用。
例如/schools/清华/students,返回所有清华大学的学生
POST方法请求服务器在数据库中创建资源,主要是在提交Web表单时。
/schools/清华/students/张三,在清华大学的学生资源,新增一个张三的学生。
POST是非幂等的,这意味着多个请求将具有不同的效果。
PUT方法请求服务器更新资源或创建资源(如果不存在)。
/schools/清华/students/张三, 对清华大学下的学生资源中,更新或者创建张三。
PUT是幂等的,这意味着多个请求将具有相同的效果。
DELETE方法请求从数据库中删除资源或其实例。
/schools/清华/students/张三,从清华大学的学生集合中,删除学生张三的资源。
使用JSON作为通信格式:
JSON阅读性更高,扩展性更强,适合各种环境和语言进行解析,现在大的互联网公司,对外提供的API基本都使用JSON。
常见的HTTP状态码:
2xx(成功类别)
200 Ok表示GET,PUT或POST成功的标准HTTP响应。
201 Created每当创建新实例时,都应返回此状态代码。 例如,使用POST方法创建新实例时,应始返回201状态代码。
204 No Content表示请求已成功处理,但未返回任何内容。
3xx(重定向类别)
304 Not Modified表示客户端已在其缓存中有响应。 因此无需再次传输相同的数据。
4xx(客户端错误类别)
这些状态代码表示客户端已提出错误请求。
400 Bad Request表示未处理客户端的请求,因为服务器无法理解客户端要求的内容。
401 Unauthorized表示不允许客户端访问资源,并应使用所需凭据重新请求。
403 Forbidden表示请求有效且客户端已通过身份验证,但不允许客户端出于任何原因访问该页面或资源。例如,有时不允许授权客户端访问服务器上的目录。
404 Not Found表示请求的资源现在不可用。
410 Gone表示已移动的请求资源不再可用。
5xx(服务器错误类别)
500内部服务器错误表示请求有效,但服务器完全混淆,并要求服务器提供某些意外情况。
503 Service Unavailable表示服务器已关闭或无法接收和处理请求。大多数情况下,例如服务器正在进行维护。
搜索、排序、过滤和分页:
所有这些操作都只是对一个数据集的查询。将不会有新的API集来处理这些操作。我们需要使用GET方法API附加查询参数。
下面看几个例子:
GET /schools ? search = 清华大学 在大学集合中,搜索清华大学
GET /schools ? sort = rank_asc 按照升序排列学校
GET /schools ? location = 北京 按照城市对学校过滤
GET /schools ? page=6 获取第六页的学校列表
使用版本控制:
例如下面两个版本地址:
http://api.yourservice.com/v1/schools/清华
http://api.yourservice.com/v2/schools/清华
在API上加入版本信息可以有效的使用户访问正确的API,v2是新开发功能,开发阶段,让所有用户访问v1,等开发完成统一切到v2。
可以有效的跨版本访问,例如在v2版本,还需要访问v1版本的一些接口
总结:
1,API接口都用小写
2,使用JSON通信
3,API带版本控制,比如v1,v2
4,使用Token令牌进行鉴权
5,路径中单词连接使用中划线-
6,使用HTTP自身的方法表示增删改查资源, GET:查询,POST:新增,PUT:更新,DELETE:删除
7,合理使用HTTP状态码,200,201,400,401,403,500。比如401表示用户身份认证失败,403表示你验证身份通过了,但是无权限操作资源