Nicht erst seit dem Hype um Microservices ist Schnittstellendesign ein essenzieller Bestandteil von Softwareentwicklung. Doch jede noch so gut definierte Schnittstelle kann an einen Punkt kommen, an dem sie weiterentwickelt werden muss. Sei es nur, weil sich die Anforderungen geändert haben. Kommt man an diesen Punkt, stellt sich die Frage: Muss ich meine Schnittstelle versionieren? Wenn ja, wie gehe ich vor? Wie müssen sich die Clients der Schnittstelle verhalten, um nicht plötzlich (nach einem neuen Release des Servers) eine böse Überraschung zu erleben? Die Weiterentwicklung einer Schnittstelle wird leider initial häufig nicht mit bedacht. Hoher Wartungsaufwand für die Bedienung alter und neuer Schnittstellen sind die Folge. Wie kann ich das verhindern? Wie muss ich bei der Weiterentwicklung vorgehen, um alte Clients nicht inkompatibel werden zu lassen und dennoch nicht in der Versionierungshölle zu landen? Diese und weitere Fragen werden in dieser Session beantwortet. Dabei werden die Konzepte nicht nur in der Theorie beleuchtet. Am Beispiel von JAX-RS zeige ich, wie Versionierung in der Praxis realisiert werden kann, ohne sich im Support alter Versionen zu verlieren.

1. @ArneLimburg @_openknowledge #WISSENTEILEN
API Versionierung
im Projektalltag

2. ÜBER UNS
• Enterprise Architect bei der
OPEN KNOWLEDGE GmbH
• Themen
• Microservices
• APIs
• Architektur
• Technologie (Java EE)
Arne Limburg

3. @ArneLimburg @_openknowledge #WISSENTEILEN
Mapping-Schichten
sind das Tor zur
Versionierungshölle

4. KLASSISCHE ARCHITEKTUR
Database
Business
Frontend

5. KLASSISCHE ARCHITEKTUR
Database
Business
Frontend
OR-Mapping
DTO-Mapping
JSON-Mapping

6. VIER MODELLE
OR-Mapping
DTO-Mapping
JSON-Mapping
{
"parent": {...}
...}

7. {
"parent": {...}
...}

8. KLASSISCHE ARCHITEKTUR
Business
Frontend
Client

9. VERSCHIEDENE MODELLE
Mapping
Schnittstelle

10. VERSCHIEDENE MODELLE
Mapping
Schnittstelle

11. VERSCHIEDENE MODELLE
Mapping
Schnittstelle

12. Schnittstelle
DTO-SCHICHT TO THE RESCUE?
Mapping

13. DTO-SCHICHT TO THE RESCUE?
Mapping
Mapping

14. DTO-SCHICHT TO THE RESCUE?
Mapping

15. JEDEM CLIENT SEINE SCHNITTSTELLE
Mapping Mapping

16. JEDEM CLIENT SEINE SCHNITTSTELLE
Mapping Mapping
Mapping Mapping

17. @ArneLimburg @_openknowledge #WISSENTEILEN
Willkommen in der
Versionierungshölle

18. VERSCHIEDENE SCHNITTSTELLEN
Mapping Mapping
Mapping Mapping

19. VERSCHIEDENE SCHNITTSTELLEN
Mapping Mapping
Mapping Mapping

20. DOMAIN DRIVEN DESIGN

21. DOMAIN DRIVEN DESIGN
„For most software projects, the primary focus
should be on the domain and domain logic“
Eric Evans, Domain-Driven Design, Addison-Wesley, © Eric Evans, 2004

22. DOMÄNE
End User
Domain
Expert
Technical
Expert
Translation
Ist auf Dauer teuer
sogar sehr teuer

23. UBIQUITOUS LANGUAGE
End User
Domain
Expert
Technical
Expert
Fachsprache als Basis
Eindeutige Begriffe
Durchgängige Nutzung

24. DOMAIN DRIVEN DESIGN
„Complex Domain Design
should be based on a model “
Eric Evans, Domain-Driven Design, Addison-Wesley, © Eric Evans, 2004

25. DOMÄNENMODELL
Repräsentation der Domäne
Fachlich korrekt und konsistent
Weiterentwicklung durch alle Beteiligten

26. DOMÄNENMODELL
Repräsentation der Domäne
Fachlich korrekt und konsistent
Weiterentwicklung durch alle Beteiligten
„Das Domänenmodell ist das Bindeglied
zwischen Domänenexperten und
Entwicklern“
Eric Evans, Domain-Driven Design, Addison-Wesley, © Eric Evans, 2004

27. DOMÄNENMODELL ALS API
Schnittstelle

28. How to escape from
Versioning Hell?

29. Tolerant Reader Pattern
Tolerant gegenüber unbekannten Feldern
Umgang mit x-extensible-enum
http://zalando.github.io/restful-api-guidelines

30. EXKURS X-EXTENSIBLE-ENUM
Beispiel
address_type:
type: string
x-extensible-enum:
- private
- business

31. Tolerant Reader Pattern
Tolerant gegenüber unbekannten Feldern
Umgang mit x-extensible-enum
Tolerant gegenüber unbekannten Statuscodes
http://zalando.github.io/restful-api-guidelines
HTTP Status 301 folgen

32. TOLERANT READER PATTERN
http://www.example.com/addresses/42
à Liefert Addresse
{
street: {
"name": "Poststraße",
"number": "1",
},
"city": "26122 Oldenburg"
}

33. TOLERANT READER PATTERN
http://www.example.com/addresses/42
Attribut hinzufügen
{
street: {
"name": "Poststraße",
"number": "1",
"additionalAdressLine": "2. Obergeschoss"
},
"city": "26122 Oldenburg"
}

34. TOLERANT READER PATTERN
Server schickt
{
street: {
"name": "Poststraße",
"number": "1",
"additionalAdressLine":
"2. Obergeschoss"
}...
}
http://www.example.com/addresses/42
Client erwartet
{
street: {
"name": "Poststraße",
"number": "1",
}...
}

35. TOLERANT READER PATTERN
http://www.example.com/addresses/42
Attribut-Umbenennung
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
},
"city": "26122 Oldenburg"
}

36. TOLERANT READER PATTERN
http://www.example.com/addresses/42
à Abwärtskompatible Änderungen: Umbenennen durch Kopieren
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
},
"city": "26122 Oldenburg"
}

37. Und was ist, wenn der Client kein
Tolerant Reader ist?

38. PROJEKTIONEN
// Client kann entscheiden, welche Felder er bekommen möchte
// Facebook Style
GET /addresses/3?fields=street,city
GET /addresses/3?fields=street.name,street.number,city
// LinkedIn Style
GET /addresses/3?fields=street:(name,number),city

39. OK, so soll sich
der Client verhalten.
Aber was ist mit dem Server?

40. Photo by Irene Fertik, USC News Service. Copyright 1994, USC.
„Be conservative in what you do,
Be liberal in what you accept
from others“
RFC 793, Robustness Principal (John Postel)

41. Es darf nichts entfernt werden
Keine Veränderung von Verarbeitungsregel
Optionales darf nie Required werden
http://zalando.github.io/restful-api-guidelines
Alles was hinzugefügt wird, muss optional sein

42. MAGNANIMOUS WRITER PATTERN
Server schickt
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1“
}...
}
http://www.example.com/addresses/42
Client erwartet
{
street: {
"name": "Poststraße",
"number": "1",
}...
}
http://tenderware.blogspot.de/2011/05/magnanimous-writer.html

43. MAGNANIMOUS WRITER PATTERN
Server schickt
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1“
}...
}
http://www.example.com/addresses/42
Client erwartet
{
street: {
"streetName": "Poststraße",
"houseNumber": "1",
}...
}
http://tenderware.blogspot.de/2011/05/magnanimous-writer.html

44. MAGNANIMOUS WRITER PATTERN
Server erwartet
PUT http://www.example.com/addresses/42
Client schickt
{
street: {
"name": "Poststraße",
"number": "1",
}...
}
http://tenderware.blogspot.de/2011/05/magnanimous-writer.html

45. MAGNANIMOUS WRITER PATTERN
PUT http://www.example.com/addresses/42
Client schickt
{
street: {
"name": "Poststraße",
"number": "1",
}...
}
http://tenderware.blogspot.de/2011/05/magnanimous-writer.html
Server erwartet
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1“
}...
}
oder
oder

46. MAGNANIMOUS WRITER PATTERN
PUT http://www.example.com/addresses/42
Client schickt
{
street: {
"streetName": "Poststraße",
"houseNumber": "1",
}...
}
http://tenderware.blogspot.de/2011/05/magnanimous-writer.html
Server erwartet
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1“
}...
}
oder
oder

47. MAGNANIMOUS WRITER UND XML
http://www.example.com/.../street
à Abwärtskompatible Änderungen
<street>
<name>Poststraße</name>
<houseNumber>0815</...>
</customer>
<xs:schema xmlns:xs:="...">
<xs:complexType name="streetType">
<xs:sequence>
...
<xs:element
name="houseNumber"
type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:schema>

48. MAGNANIMOUS WRITER UND XML
http://www.example.com/.../street
à Abwärtskompatible Änderungen
à Version 1.1
<customer>
<name>Max Mustermann</name>
<houseNumber>0815</...>
<number>0815</number>
</customer>
<xs:sequence>
...
<xs:element ...
name="houseNumber“
minOccurs="0"/>
<xs:element ...
name="number“
minOccurs="0"/>
</xs:sequence>

49. MAGNANIMOUS WRITER UND XML
http://www.example.com/.../street
à Abwärtskompatible Änderungen
à Version 1.1
<customer>
<name>Max Mustermann</name>
<houseNumber>0815</...>
<number>0815</number>
</customer>
<xs:sequence>
...
<xs:element ...
name="houseNumber“
minOccurs="0"/>
<xs:element ...
name="number“
minOccurs="0"/>
<xs:any minOccurs="0"/>
<xs:anyAttribute
processContents="lax"/>

50. MAGNANIMOUS WRITER UND XML
à Offizieller Versionssupport seit XML-Schema 1.1
<schema ... xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning">
<complexType name="street" vc:maxVersion="1.3">
...
</complexType>
<complexType name="street" vc:minVersion="2.0">
...
</complexType>
</schema>

51. MAGNANIMOUS WRITER UND JAVA
public String getName() {
return getStreetName();
}
public void setName(String name) {
setStreetName(name);
}

52. PUT UND NULL VALUES
public String getName() {
return getStreetName();
}
public void setName(String name) {
setStreetName(name);
}

53. MERGE PATCH UND NULL VALUES
PATCH /addresses/42 HTTP/1.1
Content-Type: application/merge-patch+json
Client schickt
{
street: {
"name": null,
}...
}
https://tools.ietf.org/html/rfc7396

54. MERGE PATCH UND NULL VALUES
public class Street {
private String streetName;
private String streetNumber;
public void setName(String name) { setStreetName(...
public void setNumber(String number) { setStreetNum...
}
Wird mit null aufgerufen
Wird gar nicht aufgerufen

55. MERGE PATCH UND NULL VALUES
public class Street {
private String streetName; // = null
private String streetNumber; // = null
public void setName(String name) { setStreetName(...
public void setNumber(String number) { setStreetNum...
}

56. MERGE PATCH UND NULL VALUES
public class Street {
private String streetName; // = null
private String streetNumber; // = null
public void setName(String name) { setStreetName(...
public void setNumber(String number) { setStreetNum...
}
Simple Solution:
Don‘t use PATCH at all

57. MERGE PATCH UND NULL VALUES
public class Street {
private String streetName; // = null
private String streetNumber; // = null
public void setName(String name) { setStreetName(...
public void setNumber(String number) { setStreetNum...
}
Advanced Solution:
Use initial values

58. MERGE PATCH UND NULL VALUES
public class Street {
private String streetName = "<initial value>";
private String streetNumber = "<initial value>";
public void setName(String name) { setStreetName(...
public void setNumber(String number) { setStreetNum...
}

59. MERGE PATCH UND NULL VALUES
public class Street {
private String streetName = "<initial value>";
private String streetNumber = "<initial value>";
public void setName(String name) { setStreetName(...
public void setNumber(String number) { setStreetNum...
}
Wird mit null aufgerufen
Wird gar nicht aufgerufen

60. MERGE PATCH UND NULL VALUES
public class Street {
private String streetName; // = null
private String streetNumber = "<initial value>";
public void setName(String name) { setStreetName(...
public void setNumber(String number) { setStreetNum...
}
Wird mit null aufgerufen
Wird gar nicht aufgerufen

61. ABWÄRTSKOMPATIBILITÄT
http://www.example.com/addresses/42
à Abwärtskompatible Änderungen: Umbenennen durch Kopieren
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
},
"city": "26122 Oldenburg"
}
Geht da noch mehr?

62. ABWÄRTSKOMPATIBILITÄT
http://www.example.com/addresses/42
à Zusammenführen und Teilen von Attributen
{
street: {
...
"streetName": "Poststraße",
"houseNumber": "1",
"addressLine1": "Poststraße 1",
}
...
}

63. ABWÄRTSKOMPATIBILITÄT
http://www.example.com/addresses/42
à Herausforderungen: Zusammenführen von Attributen
{
street: {
...
"streetName": "Poststraße",
"houseNumber": "1",
"addressLine1": "Poststraße 1",
}
...
}

64. ABWÄRTSKOMPATIBILITÄT
http://www.example.com/addresses/42
à Herausforderungen: Teilen von Attributen
{
street: {
...
"addressLine1": "Poststraße 1",
}
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg"
}

65. ABWÄRTSKOMPATIBILITÄT
http://www.example.com/addresses/42
à Herausforderungen: Ebene von Attributen ändern
{
street: {
...
"addressLine1": "Poststraße 1"
}
"addressLine1": "Poststraße 1",
...
}

66. ABWÄRTSKOMPATIBILITÄT
http://www.example.com/addresses/42
à Herausforderungen: Ebene von Attributen ändern
{
...
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}

67. ABWÄRTSKOMPATIBILITÄT
http://www.example.com/addresses/42
à Herausforderungen: Ebene von Attributen ändern
{
...
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
Bei jeder Modelländerung muss
eine Migrationsstrategie
einbezogen werden!

68. ABWÄRTSKOMPATIBILITÄT
public String getCity() {
return getZipCode() + " " + getCityName();
}
public void setCity(String city) {
setZipCode(city.substring(0, 5));
setCityName(city.substring(5).trim());
}

69. Was ist daran jetzt besser als an
einer Mapping-Schicht?

70. Migrations-Strategie für jede Attributänderung
Code für Migration sehr nah an der Schnittstelle
Migrations-Regeln innerhalb des Objekts
Code unabhängig

71. ABWÄRTSKOMPATIBILITÄT
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
"addressLine1": "Poststraße 1",
"addressLine2": "",
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
http://www.example.com/v1/addresses/42
à Bisher nur abwärtskompatible Änderungen

72. ABWÄRTSKOMPATIBILITÄT
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
"addressLine1": "Poststraße 1",
"addressLine2": "",
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
http://www.example.com/v1/addresses/42
à Viele Attribute deprecated

73. Wie kann ich Attribute entfernen?

74. Incompatible Change
vs. Breaking Change
http://zalando.github.io/restful-api-guidelines

75. WELCHE CLIENTS NUTZEN MICH?

76. PROVIDER CONTRACT
ProviderConsumer
A
C
B

77. CONSUMER CONTRACTS
ProviderConsumer
A
C
B

78. CONSUMER CONTRACTS
YAGNI - You Aren’t Gonna Need It!
ProviderConsumer
A
B
C

79. CONSUMER-DRIVEN CONTRACT TEST
Consumer ProviderConsumer
Contract

80. CONSUMER-DRIVEN CONTRACT TEST
• Versteht der Provider die Anfragen?
• Liefert er die erwarteten Antworten?
Consumer
Provider
Stub
Provider
Request
Generator
• Erzeugt der
Consumer die
erwarteten Anfragen?
• Kann er mit den
Antworten umgehen?

81. CONSUMER-DRIVEN CONTRACT TEST
• Startet Provider
• Interaktionen abspielen Consumer
Provider
Stub
Provider
Request
Generator
• Unit-Tests
• Responses auf
erwartete Requests
Interactions

82. CONSUMER-DRIVEN CONTRACT TEST
• Versteht der Provider die Anfragen?
• Liefert er die erwarteten Antworten?
Consumer
Provider
Stub
Provider
Request
Generator
• Erzeugt der
Consumer die
erwarteten Anfragen?
• Kann er mit den
Antworten umgehen?

83. Und wenn ich meine Consumer
nicht kenne?

84. VERSIONSSPRUNG
{
street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
"addressLine1": "Poststraße 1",
"addressLine2": "",
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
http://www.example.com/v1/addresses/42
à Bisher nur abwärtskompatible Änderungen

85. INKOMPATIBLE ÄNDERUNG
http://www.example.com/v2/addresses/42
à Versionssprung
{
"addressLine1": "Poststraße 1",
"addressLine2": "",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}

86. INKOMPATIBLE ÄNDERUNG

87. Version 2.0
ist nur inkompatibel zu 1.0!
Version 2.0 ist identisch zu 1.x!
Das erleichtert das Mapping
zwischen den Versionen!

88. Ein solcher Versionssprung ist
nicht anforderungsgetrieben,
sondern viel besser und
langfristiger planbar

89. • Über URL-Pfad
/v2/addresses
• Über Query-Parameter
/addresses?version=v2
• Über Version-Header
Api-Version: v2
• Über Version-Attribut am Media-Type
application/xml;version=v2
• Über Media-Type
application/vnd.de.openknowledge+v2+json
ERMITTELN DER VERSION

90. ABWÄRTSKOMPATIBILITÄT
Schnittstelle Schnittstelle
{ street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
"addressLine1": "Poststraße 1",
"addressLine2": "",
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
{
"addressLine1": "Poststraße 1",
"addressLine2": "“,
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
V1 V2-SNAPSHOT

91. ABWÄRTSKOMPATIBILITÄT
Schnittstelle Schnittstelle
{ street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg",
"addressLine1": "Poststraße 1",
"addressLine2": "“,
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
{
"addressLine1": "Poststraße 1",
"addressLine2": "“,
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
V1 V2-SNAPSHOT

92. ABWÄRTSKOMPATIBILITÄT
Schnittstelle
Schnittstelle
{ street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
...
}
{
"addressLine1": "Poststraße 1",
"addressLine2": "“,
"city": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
V1 V3-SNAPSHOT
Schnittstelle
{ "addressLine1": "Poststraße 1",
"addressLine2": "“,
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
},
"city": {
"zipCode": "26122",
"cityName": "Oldenburg"
}} V2

93. GRÜNE WIESE
Server
REST
Client

94. SCHLANKE ARCHITEKTUR ZU BEGINN
Schnittstelle
V1-SNAPSHOT

95. AUTOMATISIERTES MAPPING
Schnittstelle Schnittstelle
{ street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
"addressLine1": "Poststraße 1",
"addressLine2": "",
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
{
"addressLine1": "Poststraße 1",
"addressLine2": "“,
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
V1 V2-SNAPSHOT

96. FAZIT
Schnittstelle Schnittstelle
{ street: {
"name": "Poststraße",
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
"addressLine1": "Poststraße 1",
"addressLine2": "",
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
{
"addressLine1": "Poststraße 1",
"addressLine2": "“,
"location": {
"zipCode": "26122",
"cityName": "Oldenburg"
}
}
V1 V2-SNAPSHOT
It‘s never too late
Don‘t break the Client
Plane neue Versionen
Behalte alte Versionen

97. FRAGEN & DISKUSSION
? ? ?