Restful API学习

HTTP协议

URL

http是一个属于应用层的协议，特点是简洁、快速。

schema://host[:port]/path[?query-string][#anchor]

• schema　　指定低层使用的协议（例如：http，https，ftp）
• host　　服务器的ip地址或者域名
• port　　服务器端口，默认80
• path　　访问资源的路径
• query-string　　发送给http服务器的数据
• anchor　　锚

请求

组成格式：请求行，消息报头，请求正文

请求行格式：Method Request-URI HTTP-Version CRLF

举例：GET/HTTP/1.1 CRLF

请求方式：

• GET　　请求获取Request-URI所标识的资源
• POST　　在Request-URI所标识的资源后附加新的数据
• HEAD　　请求获取由Request-URI所标识的资源的响应消息报头
• PUT　　请求服务器存储一个资源，并用Request-URI作为其标识
• DELETE　　请求服务器删除Request-URI所标识的资源
• OPTION　　请求查询服务器的性能，或者查询与资源相关的选项和需求

响应

组成格式：状态行，消息报头，响应正文

状态行格式：HTTP-Version Status-Code Reason-Phrase CRLF

举例：HTTP/1.1 200 OK

常用状态码：

• 200 OK　　//客户端请求成功
• 400 Bad Request　　//客户端请求有语法错误，不能被服务器所理解
• 401 Unauthorized　　//服务器收到请求，但是拒绝提供服务
• 404 Not Found　　//请求资源不存在
• 500 Internal Server Error　　//服务器发生不可预期的错误
• 503 Server Unavailable　　//服务器当前不能处理客户端的请求

RESTful架构与其他架构的区别

效率和易用性

SOAP由于各种需求不断扩充其本身协议的内容，导致在SOAP处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所增加。

RESTful由于其面向资源接口设计以及操作抽象简化了开发者的不良设计，同时也最大限度的利用了Http最初的应用协议设计理念。

安全性

SOAP的成熟性可以给需求提供给多开发语言的，对于安全性要求较高的接口设计带来便利。所以我觉得纯粹说什么设计模式将会占据主导地位没有什么意义，关键还是看应用场景。

RESTful对于资源型服务接口来说很合适，同时特别适合对于效率要求很高，但是对于安全要求不高的场景。

如何设计RESTful API

• 资源路径（URI）
  • 在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说API中的名词应该使用复数。
• HTTP动词
  • 对于资源的操作（CURD），由于HTTP动词（谓词）表示。
  • GET：从服务器取出资源（一项或多项）。
  • POST：在服务器新建一个资源。
  • PUT：在服务器更新资源（客户端提供改变后的完整资源）
  • PATCH：在服务器更新资源（客户端提供改变的属性）
  • DELETE：从服务器删除资源。
• 过滤信息
  • 如果记录数量很多，服务器不可能都将它们返回给用户。
  • API应该提供参数，过滤返回结果。
• 状态码
  • 服务器向用户返回的状态码和提示信息，使用标准HTTP状态码。
  • 200 OK 服务器成功返回用户请求的数据，该操作是幂等的。
  • 201 CREATED 新建或修改数据成功。
  • 204 NO CONTENT 删除数据成功。
  • 400 BAD REQUEST 用户发出的请求有错误，该操作是幂等的。
  • 401 Unauthorized 表示用户没有认证，无法进行当前操作。
  • 403 Forbidden 表示用户访问是被禁止的。
  • 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。
  • 500 INTERNAL SERVER ERROR 服务器发生错误，用户将无法判断发出的请求是否成功。
• 错误处理
  • 如果状态码是4xx或者5xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可{“error”：“参数错误”}
• 返回结果
  • 针对不同操作，服务器向用户返回的结果应该符合以下规范：
    • GET/collections：返回资源对象的列表（数组）
    • GET/collections/identity：返回单个资源对象
    • POST/collections：返回新生成的资源对象
    • PUT/collections/identity：返回完整的资源对象
    • PATCH/collections/identity：返回被修改的属性
    • DELETE/collections/identity：返回一个空文档