版本化REST API和供应商特定的内容类型 [英] Versioning REST APIs and vendor specific content type
问题描述
我阅读了许多关于REST API版本的内容,例如:在这个主题中: API版本控制的最佳实践?
I read a lot about versioning REST APIs, f.e. in this thread: Best practices for API versioning?
因此我想使用HTTP-Accept-Header来指示客户端要求的版本。
但是我如何在我的申请中应用这个?因此,有哪些变化?编组人员如何知道应该使用哪个版本?我必须注册我的类型吗?
Because of that I would like to use the HTTP-Accept-Header to indicate which version the client is asking for. But how can I apply this in my application? Which changes had therefore be made? How does the marshaller know, which version should be used? Do I have to register my type?
我所知道的是我必须更改 @Produces
-Annotation
What I know is that I have to change the content of the @Produces
-Annotation
@GET
@Path("/locations")
@Produces("application/vnd.mycompany-v1+xml")
Location[] getLocations();
但还有什么需要改变?
推荐答案
你可以使用 变体
JAX-RS的机制。
You can use the Variant
mechanisms of JAX-RS.
@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教程。
编辑
根据所选变体,没有自动编组实体的方法。这需要一些手动工作。例如:
There is no automatic way to marshal an entity according to the selected variant. This requires some manual work. For example:
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。
If the versions are different enough, I'd use a JAXB annotated class for each version. Each such class would then only contain those properties that are valid for this version. JAX-RS takes care to marshal them to JSON.
这篇关于版本化REST API和供应商特定的内容类型的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!