Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
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 ...
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“
}
...
]
}
{
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
...
{
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
...
{
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
...
{
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
...
Contract = Representation
{
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/shop/products/33“...
URIs are not part of the contract!
Hypermedia Format with Method & URI
For RESTful APIs most of
“API Versioning” is not needed!
Who uses hypermedia?
... on the Client?
Content
RESTful APIs & Versioning
APIs & Versioning
JSON Versioning
Swagger Versioning
INTERF
ACE
BREAKING THE
/shop/v2.7.4/
Major
Minor
Bugfix
/shop/v2
.7.4/
/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 ...
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 ...
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
f...
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 que...
https://httpstatusdogs.com/
https://http.cat/201
201 instead of 200.
BREAKING?
HttpResponse<JsonNode> res = get("http://api.predic8.de/persons").asJson();
if (res.getStatus() == 200) {
System.out.print...
if (res.getStatus() > 200 && res.getStatus() < 299) {
System.out.println("Success!");
} else {
System.out.println("Error: ...
integer
Type Changes
BREAKING?
More specific
integer > number > string
Content
RESTful APIs & Versioning
APIs & Versioning
JSON Versioning
Swagger Versioning
INTERF
ACE
BREAKING THE
What changes more often?
Endpoints or the payload format?
XML Type
UPA constraint!
{
"name": "Mango",
"id": 57,
"weight": 0.7
}
public class Fruit {
Long id;
String name;
String language = “en“;
}
Addition...
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 schem...
JSON Schema
{
"$schema": "http://predic8.de/shop/product/v2/",
...
}
Content-Type: application/shop+json; schema=http://pr...
Content
RESTful APIs & Versioning
APIs & Versioning
JSON Versioning
Swagger Versioning
INTERF
ACE
BREAKING THE
{
"swagger": "2.0",
"host": "api.predic8.de:443",
"basePath": "/shop",
"schemes": [
"https"
],
"info": {
"title": "Fruit S...
/products/{pid}:
get:
…
responses:
'200‘:
content:
application/json:
schema:
type: object
properties:
id:
type: integer
na...
paths
/products/
get post delete
parameters
body
schema
object
properties
weight size
description
paths
/products/
get pos...
Swaggerhub
Swagger-diff
https://github.com/Sayi/swagger-diff
Summary
• RESTful APIs do not need versioning, everyday APIs do
• JSON is good for compatibility
• Evolution not Revolutio...
APIdays Helsinki 2019 - API Versioning with REST, JSON and Swagger with Thomas Bayer, Predic8
Upcoming SlideShare
Loading in …5
×

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

79 views

Published on

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

Published in: Technology
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

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

  1. 1. INTERFACE API Versioning with REST, JSON and Swagger BREAKING THE Thomas Bayer bayer@predic8.de @thomasub
  2. 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. 3. Content RESTful APIs & Versioning APIs & Versioning JSON Versioning Swagger Versioning INTERF ACE BREAKING THE
  4. 4. { "products": [ { "name": "Pineapples", "product_url": "https://api.predic8.de/shop/products/33“ } ... ] }
  5. 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. 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. 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. 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. 9. Contract = Representation { "products": [ { "name": "Pineapples", "product_url": "https://api.predic8.de/shop/products/33“ } ... ] } Contract! Does not matter!
  10. 10. URIs are not part of the contract!
  11. 11. Hypermedia Format with Method & URI
  12. 12. For RESTful APIs most of “API Versioning” is not needed!
  13. 13. Who uses hypermedia?
  14. 14. ... on the Client?
  15. 15. Content RESTful APIs & Versioning APIs & Versioning JSON Versioning Swagger Versioning INTERF ACE BREAKING THE
  16. 16. /shop/v2.7.4/ Major Minor Bugfix
  17. 17. /shop/v2 .7.4/
  18. 18. /shop/v1/ /shop/v2/ /shop/v3/ Client New Client Newest Client New Version => New Endpoint?
  19. 19. /shop/v1/Client New Client Newest Client Updated Interface, same path & version! Only introduce new versions if you break the interface!
  20. 20. How do you know if the interface is brea king?
  21. 21. What can change? • Request • HTTP • Path • Methods • Parameters • Path • Query • Header • Body • Response • HTTP • Status Codes • Header • Body
  22. 22. New endpoint? BREAKING? GET /categories/
  23. 23. API /shop/ /products/ Client /categories/ Version 1 Version 2 GET /products/
  24. 24. API /shop/ /products/ Client Version 2 Version 1 GET /categories/ 404 Not Found
  25. 25. See: https://predic8.de/rest-api-versioning.htm
  26. 26. Adding a new field „weight“ { "id": 8, "name": "Apple" } Server supports a new field „weight“.
  27. 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. 28. Direction matters! 1. Where will be the new version deployed? 2. How are the requests/responses are affected?
  29. 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. 30. https://httpstatusdogs.com/ https://http.cat/201
  31. 31. 201 instead of 200. BREAKING?
  32. 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. 33. if (res.getStatus() > 200 && res.getStatus() < 299) { System.out.println("Success!"); } else { System.out.println("Error: " + res.getStatus()); }
  34. 34. integer Type Changes BREAKING?
  35. 35. More specific integer > number > string
  36. 36. Content RESTful APIs & Versioning APIs & Versioning JSON Versioning Swagger Versioning INTERF ACE BREAKING THE
  37. 37. What changes more often? Endpoints or the payload format?
  38. 38. XML Type UPA constraint!
  39. 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. 40. Do not be strict! @JsonIgnoreProperties(ignoreUnknown=false)
  41. 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. 42. JSON Schema { "$schema": "http://predic8.de/shop/product/v2/", ... } Content-Type: application/shop+json; schema=http://predic8.de/shop/product/v2/
  43. 43. Content RESTful APIs & Versioning APIs & Versioning JSON Versioning Swagger Versioning INTERF ACE BREAKING THE
  44. 44. { "swagger": "2.0", "host": "api.predic8.de:443", "basePath": "/shop", "schemes": [ "https" ], "info": { "title": "Fruit Shop API", "version": "1.0.0", }, …
  45. 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. 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. 47. Swaggerhub
  48. 48. Swagger-diff
  49. 49. https://github.com/Sayi/swagger-diff
  50. 50. Summary • RESTful APIs do not need versioning, everyday APIs do • JSON is good for compatibility • Evolution not Revolution • Swagger allows to compare versions

×