供应商MIME类型(用于API版本控制)

时间:2013-09-23 22:26:52

标签: api rest mime-types

我已经阅读了许多关于版本化RESTful服务的Stack Overflow(和其他)帖子。 说实话,这有点压倒性。

我决定对我们的(边缘)RESTful服务使用Accept:标头,以便客户端可以请求特定版本的资源。我不清楚的是在Accept标头中指定的内容。

我经常看到的例子是:

Accept: application/vnd.mycompany.myapp.customer-v2+json

我的问题是:

  1. 我是否更正必须注册所有vnd类型? (http://www.iana.org/cgi-bin/mediatypes.pl

  2. 版本和类型(即-v2 + json)是否属于该类型,因此需要注册每个版本和类型?

  3. 有没有理由使用vnd而不是不需要注册的“x-”子类型?例如:

    Accept: application/x-mycompany.myapp-v2+json
    

    现有的API仅供内部使用,但将来会向客户公开。

  4. 不确定这是否有意义,但可以使用现有类型但添加版本吗? (当前API返回“application / json”)

    Accept: application/json-v2
    
  5. 附加版本和类型的可接受格式(例如-v2 + json)。

  6. 如果客户端要求提供不受支持的版本,该怎么办? 406是正确答案吗?客户可以请求任何版本吗?或者更一般地说,如果客户端不提供Accept标头或Accept:* / *?

  7. ,该怎么办?

    欢迎任何其他建议。当然,目标是允许更改服务为给定资源返回的内容,但不会破坏现有客户端。

    以下是我最近查看过的资源清单:

1 个答案:

答案 0 :(得分:3)

当我决定遵循jsonapi.org标准时,我决定按照你的例子所做的那样做。

关于你的问题:

  1. 您的MIME类型应该已注册
  2. 我认为应该注册每个版本和类型,因为它们是唯一类型
  3. x-前缀已弃用,如评论中所述
  4. application/json-v2无效
  5. 您可以返回415 Unsupported Media Type或仅400 Bad Request