Have you ever been frustrated by developing and documenting an HTTP API? When it comes down to defining the HTTP interface between frontend and backend, have you ever had problems specifying the parameters or the shape of the body without misunderstandings? In this talk we’ll introduce you to "Contract Driven Development" (or API Design First approach), a methodology that uses declarative API Contracts to enable developers to efficiently design, communicate, and evolve their HTTP APIs, while automating API implementation phases where possible. In order to implement this methodology, we’ll show you how to develop an API contract using OpenAPI 3 and how you can easily implement the HTTP endpoints using Vert.x Web OpenAPI.
3. How do you tell your
frontend colleague how to
get a User from the
backend?
Motivation
3
4. Poll
Motivation
4
1) Document shared between teams
2) “For that query parameter, just look
at line 13562 of UserRESTResource”
3) You’re a rockstar
developer!
5. ⓘ Start presenting to display the poll results on this slide.
How do you doc HTTP APIs?
7. OpenAPI and Contract Driven Development
7
Tl;dr a bunch of YAMLs to describe the contract, so you can finally say to your frontend colleague the name of that query parameter!
The OpenAPI Specification (OAS) defines a standard,
programming language-agnostic interface description for HTTP
APIs, which allows both humans and computers to discover and
understand the capabilities of a service without requiring access
to source code, additional documentation, or inspection of
network traffic.
The OpenAPI Specification (OAS) defines a standard,
programming language-agnostic interface description for HTTP
APIs, which allows both humans and computers to discover and
understand the capabilities of a service without requiring access
to source code, additional documentation, or inspection of
network traffic.
Source: https://github.com/OAI/OpenAPI-Specification
8. OpenAPI and Contract Driven Development
8
Source: https://swagger.io/blog/api-strategy/benefits-of-openapi-api-development/
10. OpenAPI and Contract Driven Development
10
/pets:
get:
summary: List all pets
operationId: listPets
parameters:
- name: limit
in: query
description: How many items to return at one time
required: false
schema:
type: integer
format: int32
maximum: 100
responses:
'200':
description: A array of pets
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
'500':
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
Json Schema to
identify the properties
of limit parameter
List of parameters GET
/pets understands
Limit lives
in query
params
When there is a failure, the
endpoint replies with a 500
containing a Json
The response schema refers to
the Json Schema describing
the Pets
What can I describe
with OpenAPI?
11. OpenAPI and Contract Driven Development
● Code-First: Develop the backend code, then generate the
contract
● Design-First (or Contract-driven): Develop the contract, then
implement the contract (backend code)
11
Including OpenAPI in your workflow
12. OpenAPI and Contract Driven Development
12
What is Contract-Driven Dev?
Source: https://apievangelist.com/2018/04/03/openapi-is-the-contract-for-your-microservice/
13. OpenAPI and Contract Driven Development
13
Why Contract-Driven?
● Because you want to allow people to work independently
● Because you want to ensure consistency
● Because you need strong guarantees about service contracts
● Because you, your team, your colleagues, your customers, and your partners can collaborate
● Because you can save time with automation
14. Eclipse Vert.x
14
Resource efficient
with non-blocking I/O
Asynchronous by
nature
Lightweight, modular,
flexible
Simple APIs, little
abstractions
Great ecosystem and
community
Source: https://vertx-web-site.github.io/