APIdays Helsinki 2019 - API Versioning with REST, JSON and Swagger with Thomas Bayer, Predic8

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

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

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

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

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

{
"price": 3.55,
}
{
"products": [
{
"product_url": "https://api.predic8.de/articles/87“
}
...
]
}

{
"price": 3.55,
}
{
"products": [
{
"product_url": "https://asfkafal.com/obscure-shit“
}
...
]
}

Contract = Representation
{
"products": [
{
}
...
]
}
Contract!
Does not
matter!

URIs are not part of the contract!

Hypermedia Format with Method & URI

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

/shop/v2.7.4/
Major
Minor
Bugfix

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

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

How do you know if the
interface is brea
king?

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

New endpoint?
BREAKING?
GET /categories/

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

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

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

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

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?

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

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

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

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());
}

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

integer
Type Changes
BREAKING?

More specific
integer > number > string

What changes more often?
Endpoints or the payload format?

{
"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.

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

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

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

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

/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)

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

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

APIdays Helsinki 2019 - API Versioning with REST, JSON and Swagger with Thomas Bayer, Predic8

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

APIdays Helsinki 2019 - API Versioning with REST, JSON and Swagger with Thomas Bayer, Predic8

More Related Content

What's hot (19)

Similar to APIdays Helsinki 2019 - API Versioning with REST, JSON and Swagger with Thomas Bayer, Predic8 (20)

More from apidays (20)

Recently uploaded (20)

APIdays Helsinki 2019 - API Versioning with REST, JSON and Swagger with Thomas Bayer, Predic8