RestfulAPI规范

Restful是目前最流行的API设计规范,用于Web数据接口的设计。

一、动词+宾语

  • Restful的核心思想就是,客户端发出的数据操作指令都是“动词+宾语”的结构。

  • 如:GET/articles这个接口,GET是动词,articles是宾语

  • 动词通常是五种HTTP方法,对应CRUD操作。

    1. GET:读取(read)
    2. POST:新建(create)
    3. PUT:更新(update)
    4. PATCH:更新(update)通常是部分更新
    5. DELETE:删除(delete)
  • 根据HTTP的规范,动词一律大写。

二、动词的覆盖

  1. 有些客户端只能使用GET和POST这两种方法。服务器必须接受POST模拟其他三个方法(PUT、PATCH、DELETE)。

  2. 这时,客户端发出的 HTTP 请求,要加上X-HTTP-Method-Override属性,告诉服务器应该使用哪一个动词,覆盖POST方法。

    POST /api/Person/4 HTTP/1.1
    X-HTTP-Method-Override: PUT

  3. 上面代码中,X-HTTP-Method-Override指定本次请求的方法是PUT,而不是POST。

    • 这时,客户端发出的 HTTP 请求,要加上X-HTTP-Method-Override属性,告诉服务器应该使用哪一个动词,覆盖POST方法。

三、宾语必须是名词

  1. 宾语就是 API 的 URL,是 HTTP 动词作用的对象。它应该是名词,不能是动词。
  2. 比如,/articles这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的。

    /getAllCars
    /createNewCar
    /deleteAllRedCars

四、复数 URL

  1. 既然 URL 是名词,那么应该使用复数,还是单数?

  2. 这没有统一的规定,但是常见的操作是读取一个集合,比如GET /articles(读取所有文章),这里明显应该是复数。

  3. 为了统一起见,建议都使用复数 URL,比如GET /articles/2要好于GET /article/2。

五、避免多级 URL

  1. 常见的情况是,资源需要多级分类,因此很容易写出多级的 URL,比如获取某个作者的某一类文章。

    GET /authors/12/categories/2

  2. 这种 URL 不利于扩展,语义也不明确,往往要想一会,才能明白含义。

  3. 更好的做法是,除了第一级,其他级别都用查询字符串表达。

    GET /authors/12?categories=2

  4. 下面是另一个例子,查询已发布的文章。你可能会设计成下面的 URL。

    GET /articles/published

  5. 查询字符串的写法明显更好。

    GET /articles?published=true

你可能感兴趣的:(工具,接口,restful,api,web,get)