api first with play and swagger

API First

with Play and Swagger

Some points mentioned in the The Art of Decomposing Monoliths talk:

*Akka vs Microservices *proper contract testing *forward/backward compatibility *proper JSON marshalling *DRY

THEN Java Developer

LATER Enterprise Architect

NOW Scala Consultant

TWITTER @slavaschmidt

MAIL [email protected]

mailto:[email protected]

THEN Java Developer

LATER Enterprise Architect


TWITTER @ZALANDO

MAIL [email protected]

mailto:[email protected]


@ZALANDO

Autonomy

Small in size

Full responsibility

One or more components

Systems

API FirstAutonomy

Full responsibility

One system boundary

API FirstDocument and peer review API

before writing a single line of code

Ideally, generate either your server interfaces or your test data (or both) from the spec

API First

Specification

Server Implementation

Review

Client Implementation

MisinterpretationMisrepresentation

DRY

Dave Thomas

Most people take DRY to mean you shouldn't duplicate code. That's not its intention. The idea behind DRY is far grander than that. DRY says that every piece of system knowledge

should have one authoritative, unambiguous representation.

Specification is software

It should be a single source of truth about the system

Specification

Specification

Architectural style

Specification

Architectural style

Technological stack

Architectural style

Architectural styleREST

REST Client-Server Stateless Cacheable Layered System Uniform Interface

Identification of resources Manipulation of resources through these representations Self-descriptive messages Hypermedia as the engine of application state

???

REST

Self-descriptive messages

Hypermedia as the engine of application state

???

REST APIs must be hypertext-driven

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.

???

Roy T. Fielding

+ API First

REST

???

ClientServerResource representation

Resource representation

Hypermedia controls Resource representation

Client generation

Documentation annotations

Architecture

aka Ports and Adapters

Chris Fidao https://www.youtube.com/watch?v=6SBjKOwVq0o

https://www.youtube.com/watch?v=6SBjKOwVq0o

RESTHexagonal Architecture

Hexagonal Architecture

Tran

spor

t

Tran

spor

t

Valid

ation

s

Valid

ation

s

Mod

el

Mod

el

Getting real

Easy to use

Human readable

Widest adoption

Open Source

Scala and Java

Dynamic recompilation / Hot reload

Asynchronous IO

Easy to use

URI path definitions (supports parameterisation and templating)

URI parameter definitions

Response definitions

Scheme definitions

MIME type definitions

Primitive datatypes

Complex datatypes

Structural constraints

Value constraints

Security constraints

Tags

Vendor extensions

INTERNALS

Specification

URLs

Verbs

Parameters

Security

Definitions

Specification

URLs

Verbs

Parameters

Security

Definitions Validations

Model

Test Data

Validations

Play Routes

Marshallers

Tests

Controllers

Security

[A] constructive approach to the problem of program correctness [is] a usual technique to make a program and then to test it. But, program testing can be a very effective

way to show the presence of bugs, it is hopelessly inadequate for showing their absence. The only effective

way to raise the confidence level of a program significantly is to give a convincing proof of its correctness.

-- Edsger, Wybe Di jkstra, ACM Turing Lecture, The Humble Programmer, 1972

Property based testing

Types are specifications of possible values complying to that Type

Types describe the rules that values must comply to

A possibility to generate ranges of data values for given Types

John Hughes, Haskells Quick Check

Boolean: True or False

Equality: Equal or Not Equal

Ordering: Greater, Equal or Less

Provable

Numbers

Strings

Pretty much anything not composed from Provables

Falsifiable

Plugin Architecture

AST

Play

Akka HTTP

Swagger

RAML

Apiary

Blueprint

Lagom

Architecture

http://github.com/zalando/play-swagger

http://github.com/zalando/play-swagger

Questions?

api first with play and swagger

Software