版本控制REST API和供应商特定的内容类型

Question

我读了很多关于REST API版本控制的文章，f.e.在此线程中：Best practices for API versioning?

正因为如此，我想使用HTTP-Accept-Header来指示客户端请求的版本。但是我如何在我的应用程序中应用它呢？因此，做出了哪些更改？编组程序如何知道应该使用哪个版本？我必须注册我的类型吗？

我所知道的是我必须更改@Produces-Annotation的内容

@GET
@Path("/locations")
@Produces("application/vnd.mycompany-v1+xml")
Location[] getLocations();

但是还有什么需要改变的呢？

Answer 1

您可以使用JAX-RS的Variant机制。

@GET
@Path("/locations/{id}")
@Produces(value = {"application/vnd.mycompany-v2+json", // current version
                   "application/vnd.mycompany-v1+json", // old version
                   MediaType.APPLICATION_JSON})         // fallback
public Response getLocation(@PathParam("id") Integer id,
                            @Context Request request) {
    MediaType vndTypeV1 = new MediaType("application", "vnd.mycompany-v1+json");
    MediaType vndTypeV2 = new MediaType("application", "vnd.mycompany-v2+json");
    Variant variant1 = new Variant(vndTypeV1, null, null);
    Variant variant2 = new Variant(vndTypeV2, null, null);
    Variant variantJson = new Variant(MediaType.APPLICATION_JSON_TYPE, null, null);
    List<Variant> variants = new ArrayList<Variant>();
    variants.add(variant1);
    variants.add(variant2);
    variants.add(variantJson);

    Variant selectedVariant = request.selectVariant(variants);

    Location location = someBackendService.getLocation(id);

    // Manipulate location according to which variant is the selectedVariant.
    // ...

    return Response.ok("{}")
        .header(HttpHeaders.CONTENT_TYPE, selectedVariant.getMediaType())
        .build();
}

也可以查看Java EE 6 Tutorial。

编辑

没有根据所选变体封送实体的自动方法。这需要一些手工工作。例如：

String version = extractVersionFromVariant(selectedVariant);
if ("v1".equals(version)) {
    location.setSomeV1Propery("only in v1);
} else if ("v2".equals(version)) {
    location.setSomeV2Propery("only in v2);
}
return Response.ok(location)
               .header(HttpHeaders.CONTENT_TYPE, selectVariant.getMediaType())
               .build();

如果版本差异足够大，我会为每个版本使用一个带JAXB注释的类。每个这样的类将只包含对此版本有效的那些属性。JAX-RS负责将它们编组到JSON。

Answer 2

据我所知，您不能使用JAX-RS自动路由到基于http头的不同方法。

您可以读取方法中的头文件(使用@HeaderParam或@context上的HttpHeaders，请参阅here)并调用适当的版本