RESTful API

• REST原则
  REST 即Representational State Transfer的缩写。它的理论比较抽象不太具体，理解它主要在于理解这些概念：资源、表现层、状态转换。基于REST原则设计的API，一般称为 RESTFul API，需要遵守以下这些原则 :
  • URL描述的是一个特定资源。因此描述需要名词，不能出现动词。因为动词描述的不再是资源本身，而是行为
  • 利用HTTP请求的动词表示对于资源操作的行为 , 同时，对于URL的设计一般还有约定俗成的以下补充。
  • 对于资源的描述的名词应该是层级嵌套的方式
    比如/company/department/projects。通过这种对于信息层级描述的方式，更利于实体的抽象，以及增加客户端与服务器端开发人员对于整个系统模块认知的一致性
  • 路径终点的命名考虑用复数形式，比如 /books。一般一个URL路径表示的资源会映射为数据库一系列表的记录的集合，因此使用复数更直观
• 实践设计
  实际设计restful api时的注意点包括以下：
  • 尽量使用https协议
  • 如果接口是公用且会被扩展时，应该考虑放在专有域名下，https://api.baidu.com
  • 由于api会在业务中不断地迭代，所以最好是带上版本，https://api.baidu.com/v2/
  • 最后接口路径应该尽量使用集合，也就是复数形式，https://api.baidu.com/v2/books
  • 操作类接口应该注意使用对应的动词来操作
    GET /zoos：列出所有动物园
    POST /zoos：新建一个动物园
    GET /zoos/ID：获取某个指定动物园的信息
    PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
    PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
    DELETE /zoos/ID：删除某个动物园
    GET /zoos/ID/animals：列出某个指定动物园的所有动物
    DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物
  • 参数，使用参数来进行筛选，?page=2&per_page=100：指定第几页，以及每页的记录数。
  • 返回结果，结果应该包括多种情况，异常、错误信息、正确结果{status:‘ok’,massage:‘ok’,data:{data:1}}
  • 目前而言最好使用JSON格式传输数据。

http状态码

• 当浏览者访问一个网页时，浏览者的浏览器会向网页所在服务器发出请求。当浏览器接收并显示网页前，此网页所在的服务器会返回一个包含HTTP状态码的信息头(server header)用以响应浏览器的请求。HTTP状态码的英文为HTTP Status Code。下面是常见的HTTP状态码：
  200 - 请求成功
  301 - 资源（网页等）被永久转移到其它URL
  404 - 请求的资源（网页等）不存在
  500 - 内部服务器错误
• HTTP状态码由三个十进制数字组成，第一个十进制数字定义了状态码的类型，后两个数字没有分类的作用。HTTP状态码共分为5种类型：
  1** : 信息，服务器收到请求，需要请求者继续执行操作
  2** : 成功，操作被成功接收并处理
  3** : 重定向，需要进一步的操作以完成请求
  4** : 客户端错误，请求包含语法错误或无法完成请求
  5** : 服务器错误，服务器在处理请求的过程中发生了错误
  HTTP状态码列表

异常处理

• 异常处理
  异常处理（又称为错误处理）功能提供了处理程序运行时出现的任何意外或异常情况的方法。异常处理使用 try、catch 和 finally 关键字来尝试可能未成功的操作，处理失败，以及在事后清理资源。是编程语言或计算机硬件里的一种机制，用于处理软件或信息系统中出现的异常状况(即超出程序正常执行流程的某些特殊条件)
  Python异常处理