REST-ful API Evolution Using Spring


Published on

Speaker: Ben Hale
As REST-ful data services become more widespread, it is becoming clear that they have to change to suit new consumer needs. This evolution is often disruptive to consumers, but it doesn't have to be. This session, a follow up to ‘REST-ful API Design’, discusses various strategies for evolving a REST-ful API and how the strategies can be implemented using Spring.

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

REST-ful API Evolution Using Spring

  1. 1. REST-ful API Evolution with Spring Ben Hale, Pivotal © 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
  2. 2. 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
  3. 3. 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
  4. 4. Uniform Interface • Identification of resources • Manipulation of resources • Self-descriptive messages • Hypermedia as the engine of application state 4
  5. 5. 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
  6. 6. Naive URL Scheme Changes © 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
  7. 7. 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
  8. 8. 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
  9. 9. 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
  10. 10. HATEOAS URL Scheme Changes © 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
  11. 11. 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
  12. 12. 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
  13. 13. Naive Output Changes © 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
  14. 14. 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
  15. 15. 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
  16. 16. JsonView Output Changes Courtesy of Marty Pitt © 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.
  17. 17. 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
  18. 18. 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
  19. 19. Learn More. Stay Connected. Talk to us on Twitter: @springcentral Find session replays on YouTube: