HTTP Methods 和 RESTful Service API 设计

2021-04-08 18:25

阅读:420

  • 客户端调用:客户端把要创建的数据放在HTTP请求的Body中,比如Body数据是{title: "Are your lights on", author: "Donald C. Gause"}之后发送 HTTP POST 请求到https://api.server.com/books
  • 服务端实现
    •  服务端在收到客户端 POST 来的数据时,根据POST URL,发现应该创建books数据。
    • 之后获取 body 里面的内容来创建一条新 book 记录并保存,如果一切正常,返回201表示创建成功。
    • 返回时将 HTTP Header ‘Location‘ 值设置为https://api.server.com/books/new-created-book-id
    • 客户端可以获得该条刚创建数据的 Unique ID,方便在需要进一步操作时使用

  注意:POST API 不是一个数据安全和幂等性操作,如果客户端多次调用同样的 API 会导致多条数据被创建,这些数据除了 ID 不同其他属性都相同。

  举例:

  POST https://api.server.com/books

  POST https://api.server.com/books/123456/comments

GET

  一般用于读取数据,即获取资源。成功调用 GET API 会返回相应的数据。如果请求的数据不存在可返回404(Not Found)或者由于参数不正确的原因可以返回400(Bad Request)

  • 客户端调用:客户端只要简单发送一个 HTTP GET 请求到相应的 URL 即可,请求URL 中可以带上有关参数用来对数据进行条件过滤,如:GET https://api.server.com/books?author=gause
  • 服务端实现:服务端在收到相应的请求之后根据 URL 判断应该返回什么类型的数据,并且根据 URL 参数对数据进行过滤后在放在 Body 中返回给客户端。GET 可以返回一个集合,类似数组的形式。如:

  技术分享图片

  如果客户端只请求一条数据 GET https://api.server.com/books/000,应该返回对应ID的数据即可:

      技术分享图片

   注意:GET操作是数据安全和具有幂等性的操作,也就是多次调用GET应该返回相同的数据(期间没有修改操作的前提下),并且不会导致任何数据的破坏性修改。

    API举例:

  GET https://api.server.com/books/123456
  GET https://api.server.com/books/123456/comments
  GET https://api.server.com/books/123456/comments/id001
  GET https://api.server.com/books?author=gause
PUT:一般用来更新记录,和 PATCH 不同的是,PUT 一般用于替换该记录的所有属性。PATCH 只是部分更新。和 POST 不同的是,PUT 不会生成新的资源 ID,而 POST 会生成并且返回新创建的数据 ID

  客户端调用:POST 调用方式几乎相同,比如要修改的数据是{id: "book-id-000", title: "Are your lights on", author: "Donald C. Gause"}客户端发送 HTTP PUT 请求到https://api.server.com/books。和POST不同的是,该操作会带上数据的 UID,用来定位具体要修改的这一条数据,方便后续操作。也有的设计会把ID放在URL中https://api.server.com/books/book-id-000,这样要修改的Body中的数据可以不用包含ID

  服务端实现:如果更新成功 PUT API 应该返回200。如果 PUT 请求的 body 中没有任何信息则返回204, 如果id没有找到或id格式不正确,返回404。和POST不同的是该 API 没有必要在Header中更新刚创建数据ID URL,因为我们是在修改该条数据,其 ID 之前已经被客户的获取。

  注意:PUT 操作不是数据安全的,因为这个操作改变了数据,但是PUT操作是幂等性的,对于相同的PUT请求,无论调用多少次,造成的数据修改的结果永远和调第一次时相同。
       API举例:
  PUT https://api.server.com/books/123456
    PUT https://api.server.com/books/123456/comments/id001
PATCH:PATCH 操作只更新部分数据,比如有这么一条数据{id:000, title: "Are your lights on", author: "Donald C. Gause", pub:"xyz"}PATCH 操作可能只是修改 title,或者修改 pub,具体修改的内容由body 里面的数据格式规定。而 PUT API 中 body 数据一般是要替换所有数据的属性(除了ID以外)。
  客户端调用
    和 PUT 不同的只是 Body 的数据格式,PUT 请求的 Body 一般是这样的
    {title: "Are your lights on"} 只包含部分要修改的数据
  服务端实现:服务端根据 Body 的内容对该条数据进行部分更新。成功更新数据应该返回200,当数据 ID 没有找到返回404。
  注意:PATCH 操作其实不是幂等性操作,也不是数据安全的,来自不同的客户端的 PATCH 请求可能让数据部分属性相互覆盖和冲突
  API举例:PATCH https://api.server.com/books/123456        PATCH https://api.server.com/books/123456/comments/id001
DELETE:删除一条数据,正确删除后应该返回200,如果要删除的资源ID不存在则返回404,DELETE 在HTTP 协议语义中是幂等性的,无论调用多少次之后,该数据都是同样的被删除状态。
  API举例:DELETE https://api.server.com/books/123456     DELETE https://api.server.com/books/123456/comments/id001
 
 
 
 
 
 


评论


亲,登录后才可以留言!