Tweet
Tweet

Slide 1

Slide 1 text

Spec First API Development With OpenAPI and Friends 1/98 — VarnaConf 2019 | @specter_bg

Slide 2

Slide 2 text

So you need to build an API 2/98 — VarnaConf 2019 | @specter_bg

Slide 3

Slide 3 text

Where do you start? 3/98 — VarnaConf 2019 | @specter_bg

Slide 4

Slide 4 text

The Database? 4/98 — VarnaConf 2019 | @specter_bg

Slide 5

Slide 5 text

The Clients? 5/98 — VarnaConf 2019 | @specter_bg

Slide 6

Slide 6 text

The Code? 6/98 — VarnaConf 2019 | @specter_bg

Slide 7

Slide 7 text

What about docs? 7/98 — VarnaConf 2019 | @specter_bg

Slide 8

Slide 8 text

What about tests? 8/98 — VarnaConf 2019 | @specter_bg

Slide 9

Slide 9 text

What about validation? 9/98 — VarnaConf 2019 | @specter_bg

Slide 10

Slide 10 text

And now you need to change something 10/98 — VarnaConf 2019 | @specter_bg

Slide 11

Slide 11 text

Sounds familiar? 11/98 — VarnaConf 2019 | @specter_bg

Slide 12

Slide 12 text

GET /speakers/boyan → Boyan Yordanov → Ranting at @specter_bg → PHP Varna and VarnaJS organizer → VarnaLab member → Developer @ Shtrak 12/98 — VarnaConf 2019 | @specter_bg

Slide 13

Slide 13 text

So who likes writing documentation? 13/98 — VarnaConf 2019 | @specter_bg

Slide 14

Slide 14 text

Documentation that is: → "too long to read" → "totally useless" → "not updated" 14/98 — VarnaConf 2019 | @specter_bg

Slide 15

Slide 15 text

just boring 15/98 — VarnaConf 2019 | @specter_bg

Slide 16

Slide 16 text

API Specifications 16/98 — VarnaConf 2019 | @specter_bg

Slide 17

Slide 17 text

→ machine readable → easy to write → more than documentation 17/98 — VarnaConf 2019 | @specter_bg

Slide 18

Slide 18 text

I still have to write it, though. — me 18/98 — VarnaConf 2019 | @specter_bg

Slide 19

Slide 19 text

I can do so much with it. — also me (a couple of months later) 19/98 — VarnaConf 2019 | @specter_bg

Slide 20

Slide 20 text

So why bother with an API specification? 20/98 — VarnaConf 2019 | @specter_bg

Slide 21

Slide 21 text

→ Endpoints change or disappear. → Your client is out of date. → Parameters switch types. → Tests fail. You have to go on a quest ... again. 1 1 http://www.commitstrip.com 21/98 — VarnaConf 2019 | @specter_bg

Slide 22

Slide 22 text

22/98 — VarnaConf 2019 | @specter_bg

Slide 23

Slide 23 text

23/98 — VarnaConf 2019 | @specter_bg

Slide 24

Slide 24 text

Our process has failed us 24/98 — VarnaConf 2019 | @specter_bg

Slide 25

Slide 25 text

1. little upfront design work 25/98 — VarnaConf 2019 | @specter_bg

Slide 26

Slide 26 text

2. unannounced or miscommunicated changes 26/98 — VarnaConf 2019 | @specter_bg

Slide 27

Slide 27 text

waste 27/98 — VarnaConf 2019 | @specter_bg

Slide 28

Slide 28 text

frustration 28/98 — VarnaConf 2019 | @specter_bg

Slide 29

Slide 29 text

more meetings 29/98 — VarnaConf 2019 | @specter_bg

Slide 30

Slide 30 text

Common problems → changes aren't properly tested → clients constantly wait for the API → documentation and code don't match → SDKs have another opinion 30/98 — VarnaConf 2019 | @specter_bg

Slide 31

Slide 31 text

https://blog.apisyouwonthate.com/why-do-people-dislike-json- a7d67c8d38c1 31/98 — VarnaConf 2019 | @specter_bg

Slide 32

Slide 32 text

What can we do? 32/98 — VarnaConf 2019 | @specter_bg

Slide 33

Slide 33 text

33/98 — VarnaConf 2019 | @specter_bg

Slide 34

Slide 34 text

Weeks of coding can save you hours of planning! — unknown 34/98 — VarnaConf 2019 | @specter_bg

Slide 35

Slide 35 text

Specification first 35/98 — VarnaConf 2019 | @specter_bg

Slide 36

Slide 36 text

Specifications as contracts 36/98 — VarnaConf 2019 | @specter_bg

Slide 37

Slide 37 text

Game plan 37/98 — VarnaConf 2019 | @specter_bg

Slide 38

Slide 38 text

1. discuss the design 38/98 — VarnaConf 2019 | @specter_bg

Slide 39

Slide 39 text

2. write the specification 39/98 — VarnaConf 2019 | @specter_bg

Slide 40

Slide 40 text

3. generate docs and mock API 40/98 — VarnaConf 2019 | @specter_bg

Slide 41

Slide 41 text

4. refine the specification 41/98 — VarnaConf 2019 | @specter_bg

Slide 42

Slide 42 text

5. use it in tests 42/98 — VarnaConf 2019 | @specter_bg

Slide 43

Slide 43 text

6. work on the code 43/98 — VarnaConf 2019 | @specter_bg

Slide 44

Slide 44 text

Benefits 1. single source of truth for our design 2. always up to date documentation and tests 3. work on backend and clients independently 44/98 — VarnaConf 2019 | @specter_bg

Slide 45

Slide 45 text

API Specification Formats 45/98 — VarnaConf 2019 | @specter_bg

Slide 46

Slide 46 text

46/98 — VarnaConf 2019 | @specter_bg

Slide 47

Slide 47 text

API Blueprint → quite mature → markdown based → development is open on GitHub → mostly documentation oriented → tooling for the most essential things 47/98 — VarnaConf 2019 | @specter_bg

Slide 48

Slide 48 text

RAML → yaml based → covers the whole design/development process → syntax is quite similar to the OpenAPI Specification 48/98 — VarnaConf 2019 | @specter_bg

Slide 49

Slide 49 text

JSON Schema → json based → focused on the data model → great for validation and tests → has json-hyper-schema for hypermedia 49/98 — VarnaConf 2019 | @specter_bg

Slide 50

Slide 50 text

50/98 — VarnaConf 2019 | @specter_bg

Slide 51

Slide 51 text

formerly known as Swagger 51/98 — VarnaConf 2019 | @specter_bg

Slide 52

Slide 52 text

formerly known as Swagger 52/98 — VarnaConf 2019 | @specter_bg

Slide 53

Slide 53 text

It's OpenAPI now 53/98 — VarnaConf 2019 | @specter_bg

Slide 54

Slide 54 text

About the spec → has lots of tools → yaml or json based → very active community → backed by companies and widely adopted 54/98 — VarnaConf 2019 | @specter_bg

Slide 55

Slide 55 text

OpenAPI Crash Course 55/98 — VarnaConf 2019 | @specter_bg

Slide 56

Slide 56 text

read the spec at https://spec.openapis.org/oas/v3.0.2 56/98 — VarnaConf 2019 | @specter_bg

Slide 57

Slide 57 text

Basic structure openapi: “3.0.0” info: # ... servers: # ... paths: # ... tags: # ... components: # ... 57/98 — VarnaConf 2019 | @specter_bg

Slide 58

Slide 58 text

Basic information about the API info: description: >- *Imaginary* API for managing meetups. Imagined for this **VarnaConf 2019** talk. version: '0.1' title: Meetups Are Awesome API contact: email: [email protected] name: Boyan Yordanov url: 'https://boyanyordanov.com' license: # ... 58/98 — VarnaConf 2019 | @specter_bg

Slide 59

Slide 59 text

How can users access the api servers: - url: 'https://imaginary-meetups.com/api' description: Imaginary API for managing Meetups - url: 'https://staging.imaginary-meetups.com/api' description: Staging server for the imaginary API - url: 'http://localhost:8080' description: Development version of the API 59/98 — VarnaConf 2019 | @specter_bg

Slide 60

Slide 60 text

What can the API do paths: /meetups # ... /meetups/{id} # ... /meetups/{id}/events # ... 60/98 — VarnaConf 2019 | @specter_bg

Slide 61

Slide 61 text

A path description /meetups: summary: meetups description: Meetups resource tags: # .. parameters: # .. get: # ... post: # .. 61/98 — VarnaConf 2019 | @specter_bg

Slide 62

Slide 62 text

Describing parameters /meetups: # ... parameters: - name: city in: query / path / header description: Filter meetups based on city schema: type: string 62/98 — VarnaConf 2019 | @specter_bg

Slide 63

Slide 63 text

handling array parameters /meetups: # ... parameters: - name: technologies in: query` description: Filter meetups based on city schema: type: array items: type: string style: form explode: false 63/98 — VarnaConf 2019 | @specter_bg

Slide 64

Slide 64 text

Possible responses /meetups/{id} get: responses: '200': content: application/json: schema: # ... '404': content: application/problem+json: # ... 64/98 — VarnaConf 2019 | @specter_bg

Slide 65

Slide 65 text

Schema objects → based JSON Schema draft 4 witch some things added and some taken out → support references → in future might support current versions of JSON Schema and other formats 65/98 — VarnaConf 2019 | @specter_bg

Slide 66

Slide 66 text

example schema schema: type: object properties: id: type: string format: uuid name: type: string starting-date: type: string format: date 66/98 — VarnaConf 2019 | @specter_bg

Slide 67

Slide 67 text

nullable fields city: description: either a string or null type: string nullable: true 67/98 — VarnaConf 2019 | @specter_bg

Slide 68

Slide 68 text

other schema formats still a proposal 7 response: '200': content: application/json: x-oas-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json 7 https://github.com/stoplightio/spectral 68/98 — VarnaConf 2019 | @specter_bg

Slide 69

Slide 69 text

Reference object → object with $ref property → reference objects in the same document → reference external documents → replace inline definitions for most OpenAPI components 69/98 — VarnaConf 2019 | @specter_bg

Slide 70

Slide 70 text

Replace almost anything in the spec schema: $ref: '#/components/schemas/Meetup' # ... responses: '200': content: application/json: schema: $ref: 'MeetupsListResponse.yaml' 70/98 — VarnaConf 2019 | @specter_bg

Slide 71

Slide 71 text

Components components: schemas: # ... responses: # ... parameters: # ... requestBodies: # ... headers: # ... examples: # ... 71/98 — VarnaConf 2019 | @specter_bg

Slide 72

Slide 72 text

Tools 72/98 — VarnaConf 2019 | @specter_bg

Slide 73

Slide 73 text

Editors 73/98 — VarnaConf 2019 | @specter_bg

Slide 74

Slide 74 text

VSCode with openapi-lint extention → validates and lints → resloves external references → converts OpenAPI 2.0 to OpenAPI 3.0 → intellisense for both formats 74/98 — VarnaConf 2019 | @specter_bg

Slide 75

Slide 75 text

Swagger Editor 75/98 — VarnaConf 2019 | @specter_bg

Slide 76

Slide 76 text

Apicurio 76/98 — VarnaConf 2019 | @specter_bg

Slide 77

Slide 77 text

OpenAPI GUI 77/98 — VarnaConf 2019 | @specter_bg

Slide 78

Slide 78 text

Senya Editor 3 → PhpStorm (JetBrains) plugin → smart completion → live linting → handles $refs well → preview in Swagger UI ¯\_(ϑ)_/¯ → quite expensive 3 https://senya.io 78/98 — VarnaConf 2019 | @specter_bg

Slide 79

Slide 79 text

Linters 79/98 — VarnaConf 2019 | @specter_bg

Slide 80

Slide 80 text

Speccy 4 → lints your specification → supports rulesets → docs preview with ReDoc → resolve spec in one file → supports external references written in json- schema 4 https://github.com/wework/speccy 80/98 — VarnaConf 2019 | @specter_bg

Slide 81

Slide 81 text

Spectral 7 → based entirely on rulesets → lints OpenAPI 2/3 out of the box → extremely flexible 7 https://github.com/stoplightio/spectral 81/98 — VarnaConf 2019 | @specter_bg

Slide 82

Slide 82 text

Documentation 82/98 — VarnaConf 2019 | @specter_bg

Slide 83

Slide 83 text

Swagger UI - least favorite 83/98 — VarnaConf 2019 | @specter_bg

Slide 84

Slide 84 text

Widdershins + Slate / Shins.js 84/98 — VarnaConf 2019 | @specter_bg

Slide 85

Slide 85 text

ReDoc 85/98 — VarnaConf 2019 | @specter_bg

Slide 86

Slide 86 text

Mock Servers 86/98 — VarnaConf 2019 | @specter_bg

Slide 87

Slide 87 text

Stoplight.io / Prism 5 $ npm install -g @stoplight/prism-cli $ prism mock openapi.yml APISprout 6 $ docker pull danielgtaylor/apisprout $ docker run -p 8000:8000 danielgtaylor/apisprout openapi.yaml 6 https://github.com/danielgtaylor/apisprout 5 https://github.com/stoplightio/prism 87/98 — VarnaConf 2019 | @specter_bg

Slide 88

Slide 88 text

Testing 88/98 — VarnaConf 2019 | @specter_bg

Slide 89

Slide 89 text

Postman → import trough the app → import using the API 89/98 — VarnaConf 2019 | @specter_bg

Slide 90

Slide 90 text

OpenAPI <-> JSON Schema conversion https://github.com/mikunn/openapi2schema https://github.com/wework/json-schema-to- openapi-schema 90/98 — VarnaConf 2019 | @specter_bg

Slide 91

Slide 91 text

Why convert? best of both worlds (sort of) 91/98 — VarnaConf 2019 | @specter_bg

Slide 92

Slide 92 text

Example test 2 describe Api::MeetupsController, :type => :request do describe "GET /meetups" do it 'should return a list of meetups' do # ... get '/meetups' expect(response).to have_http_status(:success) expect(response).to match_json_schema("meetups") end end end 2 https://github.com/thoughtbot/json_matchers 92/98 — VarnaConf 2019 | @specter_bg

Slide 93

Slide 93 text

Code Generation 93/98 — VarnaConf 2019 | @specter_bg

Slide 94

Slide 94 text

OpenAPI Generator → community supported fork of swagger-codegen → supports OpenAPI 3.0 → Updated templates for different languages and frameworks 94/98 — VarnaConf 2019 | @specter_bg

Slide 95

Slide 95 text

openapi.tools thanks to Phil Sturgeon and Matthew Trask 95/98 — VarnaConf 2019 | @specter_bg

Slide 96

Slide 96 text

Thank you! 96/98 — VarnaConf 2019 | @specter_bg

Slide 97

Slide 97 text

Questions? 97/98 — VarnaConf 2019 | @specter_bg

Slide 98

Slide 98 text

Resources → Specification: https://swagger.io/specification → https://github.com/OAI/OpenAPI-Specification - issues / PRs → https://apisyouwonthate.com - books/blog/slack → https://philsturgeon.uk → https://apihandyman.io → https://apievangelist.com → http://json-schema.org → http://www.commitstrip.com/en/2018/02/26/its-good-to-have- experience/ 98/98 — VarnaConf 2019 | @specter_bg