The Schema-first API design approach advocates for writing your API definition first in one of many API Specification languages before writing any code. This talk introduces you to the realm of Schema-First API design and how to get started with the OpenAPI ecosystem.

1. Schema-First API Design
with OpenAPI / Swagger
Yos Riady
yos.io
bit.ly/2uDyaSN

2. API Design process
What is OpenAPI?
Introduction Design Spec Tools Conclusion
Writing OpenAPI specs
Summary and further
learning
Tooling around
OpenAPI

3. You’re building an API

4. ● You need to:
○ Update the server implementation to support the new feature.
○ Update all client libraries / SDKs.
○ Update the documentation.
● All the above must be consistent with each other.
● Also, frontend teams are blocked until your backend API is complete.
Adding a new feature to the API

5. Is there a better way to do this?

6. Schema-First API Design
The Schema-first API design approach means writing your API definition first in
one of many API Specification languages before writing any code.

7. Iterate faster in teams
Benefits of the Schema-First Approach
Generate ArtifactsGenerate API Tests
You can generate mock
services for clients to work
with, even before backend
components are ready.
Your API Specification can
be used to generate
functional tests for the API.
Your API Specification can
be used to generate SDKs,
documentation, and server
scaffolds.

8. API Specification Languages

9. API Design process
What is OpenAPI?
Introduction Design Spec Tools Conclusion
Writing OpenAPI specs
Summary and further
learning
Tooling around
OpenAPI

10. OpenAPI / Swagger

11. What’s in an OpenAPI Specification?
● General information about the API
● Available paths e.g. /resources
○ Available operations on each path e.g. GET /resources/{id}
○ input & output for each operation

12. openapi: 3.0.0
info:
title: Sample API
description: Optional multiline or single-line description
version: 0.1.9
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
'200': # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string

13. editor.swagger.io

14. Writing an OpenAPI Specification: openapi
openapi: 3.0.0
The semantic version number of the
OpenAPI Specification version that
the OpenAPI document uses.

15. The info section provides
general information about the
API.
info:
title: Sample Pet Store App
version: 1.0.1
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
name: API Support
url: http://www.example.com/support
email: support@example.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
Writing an OpenAPI Specification: info

16. Writing an OpenAPI Specification: paths
The paths section contains the
endpoints such as /products and
operations are the HTTP methods
such as GET, POST, DELETE
paths:
/products/{id}:
get: <operation>
/orders:
post: <operation>

17. paths:
/products/{id}:
get:
operationId: getProductById
parameters:
- name: id
in: path
description: Product ID
required: true
schema:
type: integer
format: int64
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
Writing an OpenAPI Specification: paths
Each operation documents any
parameters for the operation, the
different kinds of responses, and
other metadata.

18. Writing an OpenAPI Specification: components
components:
schemas: # Schema object definition
Pet:
type: object
properties:
name:
type: string
petType:
type: string
required:
- name
- petType
The components section lets you
define common data structures
used in your API. They can be
referenced via $ref whenever a
schema is required:
$ref: '#/components/schemas/Pet'

19. editor.swagger.io

20. And more!
There are tons of
libraries and
frameworks that
support the OpenAPI
ecosystem.
Swagger Codegen
Generates server
stubs and client
libraries in over 40
languages /
platforms.
Tooling around OpenAPI
Swagger UI
Generate interactive
API documentation
that lets users try out
API calls in the
browser.

22. API Design process
What is OpenAPI?
Introduction Design Spec Tools Conclusion
Writing OpenAPI specs
Summary and further
learning
Tooling around
OpenAPI

23. Schema-First API Design
with OpenAPI / Swagger
Yos Riady
yos.io
bit.ly/2uDyaSN

24. Q&A