API Contracting:
first steps

Tomasz Ducin

25th January 2016, Warsaw

#54

Tomek Ducin

JavaScript, Python, Java

senior software consultant @ Cybercom Poland

blah, blah, blah...

@tomasz_ducin

ducin

ducin.it

Agenda

  1. FE-BE communication
  2. API development evolution
  3. API Contracting

FE

BE

What is more important?

technical point of view:

business point of view:

tight coupling

parallel development

dynamic resource allocation

 

backend unavailability

 

API

Application Programming Interface

contract agreement - no changes forcing

API development evolution

3 steps

  • C H A O S !
  • everyman for himself
  • lots of ad-hoc fixes

+ existing reference

+ single source of truth

- no strict syntax and content

- manual checks, no automation

- useless for CI

API Contracting

  • stored in repository
  • available in CI
  • used by many
    automates
  • URLs
  • HTTP methods
  • HTTP status codes
  • HTTP content-type
  • content itself 
/songs
  get
  post
  /{songId}
    get
    /file-content
      get
      post
/artists
  get
  post
    /{artistId}
      get
      /albums
        get
/albums
  get
  post
    /{albumId}
      get
      /songs
        get
/songs:
  description: Collection of available songs in Jukebox
  get:
    description: Get a list of songs based on the song title.
    queryParameters:
      songTitle:
        description: "The title of the song to search (...)"
        required: true
        minLength: 3
        type: string
        example: "Get L"
[...]

Contract

Example

[...]
    responses:
      200:
        body:
          application/json:
            example: |
              "songs": [
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440000",
                    "songTitle": "Get Lucky"
                  },
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440111",
                    "songTitle": "Loose yourself to dance"
                  },
                  {
                    "songId": "550e8400-e29b-41d4-a716-446655440222",
                    "songTitle": "Gio sorgio by Moroder"
                  }
                  ]

opportunities

  • documentation generators
  • mock data
  • stub servers
  • test generators & runners

advancement

  • the concept is here
  • the formats are here
  • the tools are still in progress
  • standards support
  • tool-to-tool compatibility

Contracting

Tool Stacks

API Blueprint

Swagger

RAML:
RESTful API Modelling Language 

[...]
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "type": "object",
                "$schema": "http://json-schema.org/draft-03/schema",
                "id": "http://jsonschema.net",
                "required": true,
                "properties": {
                  "songTitle": {
                    "type": "string",
                    "required": true
                  },
                  "albumId": {
                    "type": "string",
                    "required": true,
                    "minLength": 36,
                    "maxLength": 36
                  }
                }
              }

Swagger & RAML
use JSON Schema

how about
SOAP contracts?

https://www.youtube.com/watch?v=VvliaO3uej8

Confitura 2015

Marcin Grzejszczak - Trzymaj się reguł - Consumer-Driven Contracts

API Contracting

vs

Consumer-Driven Contracts

imbues providers with insight into their consumer obligations , and focuses service evolution around the delivery of the key business functionality demanded by consumers .

- Martin Fowler ( here)

  • FE-BE imbalance damages both
  • Contracting => independence
  • Written API docs is good, but automation is better
  • Tools are still in progress
  • this is future!

API contracting

THX!

@tomasz_ducin

4  Q&A

tomasz@ducin.it