API Versioning with REST, JSON and Swagger, Thomas Bayer, Founder and Programmer at Predic8

1. INTERFACE
API Versioning with REST, JSON and Swagger
BREAKING THE
Thomas Bayer
bayer@predic8.de
@thomasub

2. ABOUT ME: THOMAS BAYER
25 years of experience in distributed computing
REST since 2002
Cofounder of predic8 & Orientation in Objects (Germany)
Open Source Developer ( Membrane Service Proxy )
Father of three
Yogi
@thomasub

3. Content
RESTful APIs & Versioning
APIs & Versioning
JSON Versioning
Swagger Versioning
INTERF
ACE
BREAKING THE

4. {
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/shop/products/33“
}
...
]
}

5. {
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/shop/products/33“
}
...
]
}

6. {
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/shop/products/33“
}
...
]
}

7. {
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/articles/87“
}
...
]
}

8. {
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
"name": "Pineapples",
"product_url": "https://asfkafal.com/obscure-shit“
}
...
]
}

9. Contract = Representation
{
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/shop/products/33“
}
...
]
}
Contract!
Does not
matter!

10. URIs are not part of the contract!

11. Hypermedia Format with Method & URI

12. For RESTful APIs most of
“API Versioning” is not needed!

13. Who uses hypermedia?

14. ... on the Client?

15. Content
RESTful APIs & Versioning
APIs & Versioning
JSON Versioning
Swagger Versioning
INTERF
ACE
BREAKING THE

16. /shop/v2.7.4/
Major
Minor
Bugfix

17. /shop/v2
.7.4/

18. /shop/v1/
/shop/v2/
/shop/v3/
Client
New Client
Newest Client
New Version => New Endpoint?

19. /shop/v1/Client
New Client
Newest Client
Updated Interface,
same path & version!
Only introduce new versions if you break the interface!

20. How do you know if the
interface is brea
king?

21. What can change?
• Request
• HTTP
• Path
• Methods
• Parameters
• Path
• Query
• Header
• Body
• Response
• HTTP
• Status Codes
• Header
• Body

22. New endpoint?
BREAKING?
GET /categories/

23. API /shop/
/products/
Client
/categories/
Version 1 Version 2
GET /products/

24. API /shop/
/products/
Client
Version 2 Version 1
GET /categories/
404 Not Found

25. See: https://predic8.de/rest-api-versioning.htm

26. Adding a new field „weight“
{
"id": 8,
"name": "Apple"
}
Server supports a new field
„weight“.

27. Adding a new field „weight“
{
"id": 8,
"name": "Apple"
}
{
"id": 8,
"name": "Apple",
"weight": 0.4
}
Client gets the new
field? Will he ignore it?
BREAKING?

28. Direction matters!
1. Where will be the new version deployed?
2. How are the requests/responses are affected?

29. Query Parameters
• Sequence does not matter
• Unknown parameters are ignored
• Should have defaults
TIP: Do not make a query parameter mandatory!
https://api.predic8.de/shop/products/?page=2&limit=10
https://www.google.com/?q=Helsinki&Foo=true

30. https://httpstatusdogs.com/
https://http.cat/201

31. 201 instead of 200.
BREAKING?

32. HttpResponse<JsonNode> res = get("http://api.predic8.de/persons").asJson();
if (res.getStatus() == 200) {
System.out.println("Success!");
} else {
System.out.println("Error: " + res.getStatus());
}

33. if (res.getStatus() > 200 && res.getStatus() < 299) {
System.out.println("Success!");
} else {
System.out.println("Error: " + res.getStatus());
}

34. integer
Type Changes
BREAKING?

35. More specific
integer > number > string

36. Content
RESTful APIs & Versioning
APIs & Versioning
JSON Versioning
Swagger Versioning
INTERF
ACE
BREAKING THE

37. What changes more often?
Endpoints or the payload format?

38. XML Type
UPA constraint!

39. {
"name": "Mango",
"id": 57,
"weight": 0.7
}
public class Fruit {
Long id;
String name;
String language = “en“;
}
Additional Properties
are ignored Default
Property order does
not matter.

40. Do not be strict!
@JsonIgnoreProperties(ignoreUnknown=false)

41. JSON (limitations)
•JSON has no versioning features
•Renaming of fields is not supported
•JSON can be read without a schema
• Oposed to Avro, ProtoBuf

42. JSON Schema
{
"$schema": "http://predic8.de/shop/product/v2/",
...
}
Content-Type: application/shop+json; schema=http://predic8.de/shop/product/v2/

43. Content
RESTful APIs & Versioning
APIs & Versioning
JSON Versioning
Swagger Versioning
INTERF
ACE
BREAKING THE

44. {
"swagger": "2.0",
"host": "api.predic8.de:443",
"basePath": "/shop",
"schemes": [
"https"
],
"info": {
"title": "Fruit Shop API",
"version": "1.0.0",
},
…

45. /products/{pid}:
get:
…
responses:
'200‘:
content:
application/json:
schema:
type: object
properties:
id:
type: integer
name:
type: string
vendor:
type: integer
links:
getVendorById:
operationId: getVendorById
parameters:
vid: '$response.body#/vendor‘
/vendors/{vid}:
get:
operationId: getVendorById
parameters:
- in: path
name: vid
schema:
type: integer
{
“id“: 357,
“name“: “Dauerlutscher“,
“vendor_url“: “/vendor/27“,
“vendor“: 27
}
/vendors/27
GET /products/357
Swagger 3
Link = fn(Response + Swagger)

46. paths
/products/
get post delete
parameters
body
schema
object
properties
weight size
description
paths
/products/
get post delete
parameters
body
schema
object
properties
weight size
description
==
Version a Version b

47. Swaggerhub

48. Swagger-diff

49. https://github.com/Sayi/swagger-diff

51. Summary
• RESTful APIs do not need versioning, everyday APIs do
• JSON is good for compatibility
• Evolution not Revolution
• Swagger allows to compare versions