The Leading API for Financial Services Search, Acquisition ......Schematizing A Notes API Using...

+

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


3

01 Introduction


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


5

Why should you care?


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


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


8

02 Explaining the schema


9

Follow Along With Us!

https://evenhacks.com/workshop


10

Schematizing A Notes API Using Swagger

A Basic Note Taking App

● Create Note

● Edit Note

● Delete Note

● List Notes


11


● 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


12


● We will then use the schema to

○ Generate documentation

○ Scaffold a service

○ Make REST clients


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.


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


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.


16

Schematizing A Notes API: Create A Note


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.


18

Schematizing A Notes API: Create A Note (Cont.)


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


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.


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.


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.


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


24

Schematizing A Notes API: Tags Are Super Important! (Cont.)

WITH NO TAGS WITH TAGS


25

03 Demo


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.


27

● How about Slate?

○ Easy to customize

○ Store docs as Markdown on VCS

○ Deploy? Copy static assets

Schematizing A Notes API: Generating Docs (Cont.)


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.)


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


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


31

Schematizing A Notes API: Explore The Service


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


33

Schematizing A Notes API: REST Client Codegen


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


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

The Leading API for Financial Services Search, Acquisition ......Schematizing A Notes API Using...

Documents

Transcript of The Leading API for Financial Services Search, Acquisition ......Schematizing A Notes API Using...