当用户使用我的RESTful API的相同主要(但不同的次要)版本时,如何管理资源更新？

2023年10月24日 189次阅读

想象一下以下场景.我为我的图书馆服务创建并发布了Library API的第一个版本(v1.0).它希望所有新书都使用以下三个值发布：

POST /books HTTP/1.1
Content-Type: application/json
...
{
  "title":"The Life of Beethoven",
  "author":"David Wyn Jones",
  "publisher":"Cambridge University Press"
}

--------
HTTP/1.1 201 Created
Location: http://example.com/books/12345

一些用户开始使用此API.几个月后,我发现如果他们有这些信息,我需要为用户提供发布版本的选项.因此,我向我的API(v1.1)发布了一个小的,向后兼容的扩展,以便现在接受编辑属性但仍然是可选的.现在Joe,我的一个用户,可以成功发布以下内容：

PUT /books/12345 HTTP/1.1
Content-Type: application/json
...
{
  "title":"The Life of Beethoven",
  "author":"David Wyn Jones",
  "publisher":"Cambridge University Press",
  "edition":"First"
}

然后有这个：

GET /books/12345
Accept: application/json

返回：

HTTP/1.1 200 OK
Content-Type: application/json
{
  "title":"The Life of Beethoven",
  "author":"David Wyn Jones",
  "publisher":"Cambridge University Press",
  "edition":"First"
}

但是,假设Nancy没有将API的使用升级到v1.1;她还在1.0.因此,她从未发布过包含其版本信息的书籍.她发出GET(如上所述)并获得信息,但会被忽略(因为她可以忽略她不理解的属性).

但是,如果Nancy需要检索此资源然后通过她的1.0 API更新它,这一切都会崩溃.她的要求如下：

PUT /books/12345 HTTP/1.1
Content-Type: application/json

{
  "title":"The Life of Beethoven",
  "author":"David Wyn Jones",
  "publisher":"Cambridge University Press"
}

这个PUT应该完全取代这个资源的表示,对吧？这是否意味着服务器需要完全消除版本属性,将Joe的编辑属性呈现为null？服务器应该足够聪明,只更新属性或提供的资源,还是客户端负责传递它不理解的属性？前者意味着更多的服务器工作,但后者意味着只有一个编码不良的客户端可能会为其他客户端搞砸服务器资源.

还有其他方法可以解决这个问题吗？你最近解决了这个问题,你是怎么做到的？

最佳答案 如果您正在尝试向后兼容的服务器,那么我将使服务器仅在传递显式为null的字段值时删除值,例如

{
  "title":"Fahrenheit 451",
  "author":"Ray Bradbury",
  "publisher":"Penguin",
  "edition": null
}

这样,针对v1.1 API编码的客户端就能够明确删除该字段值,但那些针对v1.0的客户端不会意外地进行更改.

点赞