REST-ful API Evolution Using Spring
-
Upload
spring-io -
Category
Technology
-
view
483 -
download
2
description
Transcript of REST-ful API Evolution Using Spring
![Page 1: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/1.jpg)
© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
REST-ful API Evolution with SpringBen Hale, Pivotal
https://github.com/nebhale/spring-one-2013
![Page 2: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/2.jpg)
Your REST-ful API... V2• A REST-ful API isn’t the end
• All things change, your API must accommodate these changes
• How do you manage change–Can you force all clients to upgrade simultaneously?–Maintain backwards compatibility?
2
![Page 3: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/3.jpg)
To the RESTque!• REST is limited (or limiting)
–Bad: not a whole lot of options for managing change–Good: not many things to worry about when managing change
• REST gives us all the building blocks we need to make system that evolve
3
![Page 4: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/4.jpg)
Uniform Interface• Identification of resources
• Manipulation of resources
• Self-descriptive messages
• Hypermedia as the engine of application state
4
![Page 5: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/5.jpg)
HTTP’s Uniform Interface• URI’s identify resources• HTTP verbs describe a limited set of operations that can be
used to manipulate a resource–GET–DELETE–PUT–POST–less used other verbs
• Headers help describe the messages
5
![Page 6: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/6.jpg)
© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
Naive URL Scheme Changes
![Page 7: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/7.jpg)
Change API “Version”• Changing the “version” of an API seems like a good idea
–Just add some additional entries to @RequestMapping–Re-use lots of code
• But it breaks down really quickly–What if the Cat payloads needed to be different?–What if some operation (e.g. creating a Cat) is slightly different
between the two versions?–How do you communicate API changes to consumers?
7
![Page 8: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/8.jpg)
What is HATEOAS?• Hypermedia As The Engine Of Application State
• The client doesn’t have a built-in knowledge of how to navigate and manipulate the model
• Instead server provides that information dynamically to the user
• Implemented by using link relations and media types
8
![Page 9: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/9.jpg)
Link Relations• A client cannot be expected to know what a resource is
related to and where those relations are located• The server describes these relations as part of its payload• Link has two parts–rel–href
• rel values are “standardized” so client can recognize them–<link rel=”stylesheet” href=”...”/>–{“rel”: “doors”, “href”: “...”}
9
![Page 10: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/10.jpg)
© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
HATEOAS URL Scheme Changes
![Page 11: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/11.jpg)
Using HATEOAS• Using HATEOS means that clients do not have to be changed
if URIs change–URIs are opaque to consumers
• Using HATEOAS can seem like a lot of initial setup work–Spring HATEOAS/Spring 4 makes it easier–Use the request mappings you already have to generate links
11
![Page 12: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/12.jpg)
Media Types• A resource can be represented in different ways
–JSON, XML, etc.• A client doesn’t know what a server is going to send it• A server doesn’t know what a client can handle• Content types are negotiated using headers
–Client describe what it wants with Accept header–Server (and client during POST and PUT) describes what it is
sending with Content-Type header
12
![Page 13: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/13.jpg)
© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
Naive Output Changes
![Page 14: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/14.jpg)
Using Media Types• Rich media types allow a server to uniquely identify not only
types, but versions of types–Fine granularity allows each type to evolve at different rates–Types can all be based on JSON/XML (+json, +xml)
• Defining and documenting a different media types for every entity in your system can be time consuming–Offset by the ease in which clients can consume changes
14
![Page 15: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/15.jpg)
Duplicating Code• Having V1/V2 classes leads to a lot of duplicated code
–types–repositories–services
• Backwards compatible changes are typically additive–Base classes don’t solve the duplication other than of types–Jackson JsonView
15
![Page 16: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/16.jpg)
© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
JsonView Output Changes
Courtesy of Marty Pitthttps://github.com/martypitt/JsonViewExample
![Page 17: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/17.jpg)
Using JsonViews• Allows you simply annotate a type
–A single backwards compatible type–Annotated so that it’s clear what exists in each version
• It is Jackson specific, but most serializers (JSON or XML) have an equivalent function.
17
![Page 18: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/18.jpg)
Round Up• APIs change and your code needs to cope with that
–The trick is managing the evolution of your API• Don’t look at REST as a limiter
–Its simplicity frees you• Embrace HATEOAS
–Link relations–Media Types
• If using Jackson, JsonViews can be used to build an annotation model for versioning
18
![Page 19: REST-ful API Evolution Using Spring](https://reader036.fdocuments.us/reader036/viewer/2022081507/554f94e3b4c905d25b8b5416/html5/thumbnails/19.jpg)
Learn More. Stay Connected.
https://github.com/nebhale/spring-one-2013
Talk to us on Twitter: @springcentralFind session replays on YouTube: spring.io/video