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.

1. Contract-driven
development with
OpenAPI 3 and
Vert.x
Francesco Guardiani @slinkydeveloper
Software Engineer, Red Hat

2. @slinkydeveloper
routerFactory
.operation("slinkydeveloperAboutMe")
.handler(context ->
context
.json(new JsonObject()
.put("first_name", "Francesco")
.put("last_name", "Guardiani")
.put("employer", "Red Hat")
.put("job", "Software Engineer - Middleware")
.put("education", "BsC IT Engineering @ PoliMi")
.put("oss_contributions", new JsonArray()
.add("Eclipse Foundation member")
.add("Knative Eventing approvers member")
).put("social", new JsonObject()
.put("website", "slinkydeveloper.com")
.put("mail", "fguardia@redhat.com")
.put("github", "@slinkydeveloper")
.put("twitter", "@SlinkyGuardiani"))
)
);2

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?

6. HTTP service contracts
should be no different from
Java APIs!
Motivation
6
Schematic
Versioning
Description
Metadata

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/

9. And more! OpenAPI.Tools
OpenAPI and Contract Driven Development
9
OpenAPI
Generator
Microcks

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/

15. Eclipse Vert.x
15

16. Eclipse Vert.x
16
● Documentation
● Introduction to Vert.x - Deven Philips
● Real-world HTTP performance benchmarking, lessons
learned - Julien Viet
● Yes, JavaScript Is Faster Than Java (When You Use
GraalVM)! - Paulo Lopes
● Modern app programming with RxJava and Eclipse Vert.x -
Thomas Segismont
● Vert.x in action - Julien Ponge

17. CONFIDENTIAL Designator
Demo demo
demo demo
demo demo
demo demo
17

18. Demo demo demo demo
18
1. Develop the contract with Apicurio
2. Implement the API backend with Vert.x
3. Test it with Postman
4. Hope it works!

19. Questions?

20. Github: @slinkydeveloper
Twitter: @SlinkyGuardiani
Thank you!