rest-ful api evolution using spring

© 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

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

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

Uniform Interface• Identification of resources

• Manipulation of resources

• Self-descriptive messages

• Hypermedia as the engine of application state

4

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

© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.

Naive URL Scheme Changes

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

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

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

© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.

HATEOAS URL Scheme Changes

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

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

© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.

Naive Output Changes

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

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

© 2013 SpringOne 2GX. All rights reserved. Do not distribute without permission.

JsonView Output Changes

Courtesy of Marty Pitthttps://github.com/martypitt/JsonViewExample

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

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

Learn More. Stay Connected.

https://github.com/nebhale/spring-one-2013

Talk to us on Twitter: @springcentralFind session replays on YouTube: spring.io/video