README

当您想通过依赖于HTTP头中的 Accept（输出）和 Content-Type（输入）来对基于Symfony的REST API进行版本控制时，此库很有用。

此库通过构建在强大的 Symfony Serializer 组件之上来实现所有这些。

相同数据的不同格式

例如：假设在您的应用程序中，您要求获取有关用户的信息，并且您还指定了所需的 Accept 头

GET http://myapi.myapp.com/user/123
Accept: application/myapp;version=1;format=json

您将得到类似以下内容

{
  "user": {
    "id": 123,
    "name": "sobolan",
    "email": "someemail@example.com",
    "age": 99
  }
}

但是，假设您的移动应用程序只知道如何读取/解析XML内容。因此，您只需要更改 format 参数的值

GET http://myapi.myapp.com/user/123
Accept: application/myapp;version=1;format=xml

现在您将得到类似以下内容

<response>
    <user>
        <id>123</id>
        <name>sobolan</name>
        <email>someemail@example.com</email>
        <age>99</age>
    </user>
</response>

相同的数据，不同的格式 ;). 并且，正如您将看到的，它将不需要在您的应用程序中添加额外的代码行。

同时支持不同的响应结构

假设在某些时候，您不希望此路由再返回用户ID，因为它是系统内部的一个值。

您可以简单地将其删除。但所有您的iOS/Android/桌面客户端都依赖于它。如果您删除它，这些应用程序将会崩溃。

相反，您可以使用此库，并让它同时支持带有用户ID和不带用户ID的响应。这正是 version 参数的作用

GET http://myapi.myapp.com/user/123
Accept: application/myapp;version=1;format=json

响应

{
  "user": {
    "id": 123,
    "name": "sobolan",
    "email": "someemail@example.com",
    "age": 99
  }
}

如果您使用不同的版本，比如 "2"，API可以这样做

GET http://myapi.myapp.com/user/123
Accept: application/myapp;version=2;format=json

响应

{
  "user": {
    "name": "sobolan",
    "email": "someemail@example.com",
    "age": 99
  }
}

请注意，"id" 字段缺失。使用此库做这个非常简单。

您这样做之后，您只需要 逐步（并按自己的时间表）将客户端迁移到使用API的版本 "2"。

完成时，只需将API的默认版本提升，使 "id" 默认不显示，即可完成操作！

不再有压力同步部署，也没有更多关于客户端可能崩溃或不崩溃的噩梦 ;)

如何使用它

有关如何使用此库的完整文档，请参阅此处： /doc/howtouse.md。

请注意，起初可能更复杂或更困难实施。但一旦您习惯了它及其功能，它就会感觉更自然。

完整示例

使用此库的完整示例可在此处找到： sobolan/rest-negotiator-example。

许可证

此库在MIT许可证下发布。