Upload
others
View
2
Download
0
Embed Size (px)
Citation preview
+
The Leading API for Financial Services Search, Acquisition and Monetization
Schema Driven API Design
October 9, 2019
© 2019 - CONFIDENTIAL
2
Agenda
1 - Introduction
2 - Explaining The Schema
3 - Demo
4 - Q&A
© 2019 - CONFIDENTIAL
3
01 Introduction
© 2019 - CONFIDENTIAL
4
Profile
Product Manager – Zack
Lead Consumer Engineer – Alex
Lead Portal Engineer – David
Lead Finance Engineer – Ross
CTO – Kevin
Role: Understands how the API fits together and identifies opportunities to move it forward
Role: Builds software to provide a client facing experience on top of our public API
Role: Builds software in order to administer our platform via our API. Requires a deep understanding of our private end points
Role: Builds software to extract meaningful financial information from the internal workings of and interactions between the services that make up our platform
Role: Thinks strategically about our architecture; understanding our architecture at a glance, how all the pieces fit together and how we can improve it
© 2019 - CONFIDENTIAL
5
Why should you care?
© 2019 - CONFIDENTIAL
6
Schema Driven Design
● Schema Driven Design: build your API from
schema design outwards
○ allows us to take an API-first approach to
building new ideas and features and scale
as a platform, not just a product
● OpenAPI is a schema driven design tool that
can be used as a common language to
describe technical capabilities across all
teams
© 2019 - CONFIDENTIAL
7
Schema Driven Design
● Creates a holistic picture of the API / stack to
discover new use cases
● Build a common understanding that
connects the needs of users to engineering
efforts
© 2019 - CONFIDENTIAL
8
02 Explaining the schema
© 2019 - CONFIDENTIAL
9
Follow Along With Us!
https://evenhacks.com/workshop
© 2019 - CONFIDENTIAL
10
Schematizing A Notes API Using Swagger
A Basic Note Taking App
● Create Note
● Edit Note
● Delete Note
● List Notes
© 2019 - CONFIDENTIAL
11
Schematizing A Notes API Using Swagger
● Swagger (now known as OpenAPI) is a way
to declaratively describe an API and all of
its resources.
● An ‘empty’ definition is visible on the right,
today we will dive into schematizing
○ Data
○ Endpoints
○ Authorization schemes
© 2019 - CONFIDENTIAL
12
Schematizing A Notes API Using Swagger
● We will then use the schema to
○ Generate documentation
○ Scaffold a service
○ Make REST clients
© 2019 - CONFIDENTIAL
13
Schematizing A Notes API: Start With The Data
Start by modeling your domain objects!
● Let’s describe a simple note resource:
○ id
○ title
○ body
○ created_at
● We don’t want title to be too long, so we set a
maxLength
○ The example field shows up when generating
documentation.
© 2019 - CONFIDENTIAL
14
Schematizing A Notes API: Start With The Data
● readOnly: true excludes a field from
appearing in client requests (and should appear
in responses from the server only)
○ writeOnly (not shown) is the inverse
● created_at is an ISO-8601 formatted string
(format: “date-time”)
○ Other useful types such as email and uuid
also exist
© 2019 - CONFIDENTIAL
15
Schematizing A Notes API: Create A Note
● We should be able to make the following
request
● title and body were marked required in
our model
● id and created_at are marked readOnly so
we can still use the Note schema without
allowing those fields for our create
endpoint.
© 2019 - CONFIDENTIAL
16
Schematizing A Notes API: Create A Note
© 2019 - CONFIDENTIAL
17
Schematizing A Notes API: Create A Note (Cont.)
● Let’s also model a simple validation error
schema
● We should be able to
○ Report multiple validation errors with one
response
○ Associate errors with the key for a
respective field in a JSON request body,
querystring, or path parameter.
© 2019 - CONFIDENTIAL
18
Schematizing A Notes API: Create A Note (Cont.)
© 2019 - CONFIDENTIAL
19
Schematizing A Notes API: Read Paginated Notes
● We should be able to
○ Filter notes by their title
■ GET /notes?title=gift%20list
○ Paginate through the response
■ GET /notes?limit=5&offset=10
© 2019 - CONFIDENTIAL
20
Schematizing A Notes API: Read Paginated Notes
● responses can include headers, too!
○ X-Total-Count lets the user know
how many note resources exist in total
for their query
● Ideally, limit and offset are standardized
across paginated GET endpoints in your API.
Instead of redefining them everywhere, we
can place them in components and $ref them.
© 2019 - CONFIDENTIAL
21
Schematizing A Notes API: Describing Authorization Schemes
● The components block can also hold
securitySchemes used to describe how to
authorize requests to your API
● This example uses the authorizationCode
flow, but implicit, password, and
clientCredentials flows are also
supported.
● Scopes listed here can be used to declare
auth requirements in endpoint definitions.
© 2019 - CONFIDENTIAL
22
Schematizing A Notes API: Using Authorization Schemes
● The auto generated documentation and client
will now tell the user to expect an OAuth token
with the note:write scope.
● It would also be helpful to add standardized
responses for 401 and 403 authorization errors.
© 2019 - CONFIDENTIAL
23
Schematizing A Notes API: Tags Are Super Important!
● Out of box, OpenAPI will group together all
paths under a tag called default.
● The documentation and codegen tools use
tags to semantically split up docs into
sections and REST clients into classes.
with no tags
with tags
© 2019 - CONFIDENTIAL
24
Schematizing A Notes API: Tags Are Super Important! (Cont.)
WITH NO TAGS WITH TAGS
© 2019 - CONFIDENTIAL
25
03 Demo
© 2019 - CONFIDENTIAL
26
Schematizing A Notes API: Generating Docs
● While the OpenAPI schema supports
summary and description tags, this is
probably not the home for cohesive docs.
● Swagger-ui great at visualizing the schema,
but misses the mark on allowing for more
detail.
○ Needs lots of customization.
© 2019 - CONFIDENTIAL
27
● How about Slate?
○ Easy to customize
○ Store docs as Markdown on VCS
○ Deploy? Copy static assets
Schematizing A Notes API: Generating Docs (Cont.)
© 2019 - CONFIDENTIAL
28
● Generate Slate docs with Swagger via
Mermade/widdershins ○ npm install -g widdershins
● Get started in ~1 minute
○ Fork slatedocs/slate and clone
■ Or download the zip ○ cd slate ○ widdershins ../notes.yaml -o source/index.html.md
○ bundle ○ bundle exec middleman serve
Schematizing A Notes API: Generating Docs (Cont.)
© 2019 - CONFIDENTIAL
29
● Visit editor.swagger.io
● Paste your API definition in the
editor
● Choose Generate Server
○ Choose scala-akka-http-server ● Unzip the archive
● Run It!
Schematizing A Notes API: Generate An Akka HTTP Service
© 2019 - CONFIDENTIAL
30
● The Akka scaffold contains an API
service with routes already defined,
and all models included under the
schema block.
Schematizing A Notes API: Explore The Service
© 2019 - CONFIDENTIAL
31
Schematizing A Notes API: Explore The Service
© 2019 - CONFIDENTIAL
32
Schematizing A Notes API: REST Client Codegen
● Generating a client is simple
● Manual download from Swagger
● Or Automate It!
○ Clone the codegen utility
○ Build it
○ Use one of the available
generators
© 2019 - CONFIDENTIAL
33
Schematizing A Notes API: REST Client Codegen
© 2019 - CONFIDENTIAL
34
Schematizing A Notes API: Exploring A TypeScript Ng Client
● Let’s generate the typescript-angular client next
○ Import it into an Angular project
● Notice that the docstrings contain the summary for
parameters we defined in the schema earlier!
● noteService also has a configuration field that can
be used to store an API access token and control other
client behaviors
© 2019 - CONFIDENTIAL
35
Already Have An API? Generate A Schema From Your Codebase!
● Writing schema by hand for a large codebase can be a daunting task.
● Fortunately, libraries exist for popular frameworks that will generate an API spec for
you from existing code
○ Many of these also embed an instance of swagger-ui that you can use to help serve as
docs for local development!
● Check out the following repos for your framework
● Play
○ iheartradio/play-swagger
● Express
○ pgroot/express-swagger-generator
● Ruby on Rails
○ rswag/rswag
● Django
○ axnsan12/drf-yasg
● Phoenix
○ xerions/phoenix_swagger
● .NET
○ domaindrivendev/Swashbuckle
+
The Leading API for Financial Services Search, Acquisition and Monetization
Q&A