jdd2014: rest api versioning practice: from header to model - Łukasz wierzbicki
DESCRIPTION
Why REST API should be backward compatible and why it is hard to achieve. The talk will be about that and other problems we have encountered in Kontakt.io when building platform for worldwide services.TRANSCRIPT
![Page 1: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/1.jpg)
About me
Łukasz Wierzbicki • +10 years of
professional experience
• software engineer, architect, manager
![Page 2: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/2.jpg)
Motivation
• lots of ideas how to mark versions
• lots of theory
• ...little practise
• any actual solution?
![Page 3: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/3.jpg)
Why do we need versioning?
• new fields in particular
resource
• we don't need some
fields any longer
• we're startup
• people are already
using our API
Why, why, why?
![Page 4: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/4.jpg)
Assumptions
• business logic returns model
• controllers return views
• object-json/xml/? mapping done
transparently
![Page 5: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/5.jpg)
Possibilities
• several versions of model,
• model as a “view”
• one object mapper
cons: a lot of code, DAOs and services pros: don't see any
no 1
![Page 6: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/6.jpg)
Possibilities, flow
cons: a lot of code, DAOs and services pros: don't see any
no 1
Dao 1
Dao 2
Service 2
Service 1 Backend 1
Backend 2
Model 2
Model 1 Controller 1
Controller 2 Response
Response
Version Router Request
![Page 7: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/7.jpg)
Possibilities • one model
• converters
• several versions of view objects
• one object mapper
no 2
![Page 8: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/8.jpg)
Possibilities, flow
no 2
cons: still a lot of boilerplate code pros: less code than previously
Dao Service
Backend 1
Backend 2
Converter 1
Converter 2
Response
Response
Version Router Request
Model
View 1
View 2
Controller 1
Controller 2
Model
![Page 9: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/9.jpg)
Possibilities • one model
• one view/proxy factory
• several versions of dynamic proxies
• one object mapper
no 3
![Page 10: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/10.jpg)
public class Address {
private final String street;
private final String city;
public Address(String street, String city) { super();
this.street = street; this.city = city;
}
public String getStreet() { return street;
}
public String getCity() { return city;
} }
@View public interface AddressV1 {
String getStreet(); @Property("city")
String getTown();
@Provider(Public.class ) Boolean getPublic();
class Public implements Provider<Address> { @Override
public Object get(Address source) { return true;
} }
}
Some code...
![Page 11: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/11.jpg)
Model
Possibilities, flow
no 3
cons: some magic to write/handle pros: even less code to handle
Dao Service
Backend 1
Response
Response
Version Router Request
View 2
Controller 1
Controller 2
Proxy Factory
Backend 2
View.class
View 1
![Page 12: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/12.jpg)
Possibilities
• one model
• view factory having list of properties
• map as a view
• one object mapper
no 4
![Page 13: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/13.jpg)
Possibilities, flow
no 4
Dao Service
Backend 2
View Factory 1
Response
Response
Version Router Request
Map
Map
Controller 1
Controller 2
cons: some magic to write/handle pros: small amount of code, partial resources
View Factory 2
Backend 1
![Page 14: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/14.jpg)
Possibilities • lots of combinations
• i.e. one view, one object mapper public class AddressView {
@Version("1", "2", "3") private String street;
@Version1 @Version3("town") private String city;
}
no ...
![Page 15: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/15.jpg)
Our choice - no 4
• because it is easy to use
• because of less boilerplate code,
and we don't have time to make /
maintain it
• because we wanted to have
“partial resources”
![Page 16: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/16.jpg)
How?
• converters get properties values and put them to maps
• include list: “length”, user.role”, “user.id”, “user.name”
• exclude list - great for small changes
• “generated fields” - when hotfix needed
• “mappings” - “name from model” -> “name in json”
![Page 17: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/17.jpg)
Our api… foreword
• REST but not RESTful/
HATEOAS
• Just Http GETs and POSTs
• Verbs in paths, i.e.: create,
update, assign
![Page 18: JDD2014: REST API versioning practice: from header to model - Łukasz Wierzbicki](https://reader033.vdocument.in/reader033/viewer/2022052907/55933a3e1a28ab142d8b4638/html5/thumbnails/18.jpg)
Thank You!