Design First APIs with OpenAPI - BG PHP 19

Slide 1

Slide 1 text

DESIGN FIRST APIS WITH OPENAPI AND FRIENDS 1/92 — BulgariaPHP 2019 | @specter_bg

Slide 2

Slide 2 text

SO YOU NEED TO BUILD AN API 2/92 — BulgariaPHP 2019 | @specter_bg

Slide 3

Slide 3 text

WHERE DO YOU START? 3/92 — BulgariaPHP 2019 | @specter_bg

Slide 4

Slide 4 text

THE DATABASE? 4/92 — BulgariaPHP 2019 | @specter_bg

Slide 5

Slide 5 text

THE CLIENTS? 5/92 — BulgariaPHP 2019 | @specter_bg

Slide 6

Slide 6 text

THE CODE? 6/92 — BulgariaPHP 2019 | @specter_bg

Slide 7

Slide 7 text

WHAT ABOUT DOCS? 7/92 — BulgariaPHP 2019 | @specter_bg

Slide 8

Slide 8 text

WHAT ABOUT TESTS? 8/92 — BulgariaPHP 2019 | @specter_bg

Slide 9

Slide 9 text

WHAT ABOUT VALIDATION? 9/92 — BulgariaPHP 2019 | @specter_bg

Slide 10

Slide 10 text

YOU SOMEHOW MANAGE TO GET GOING AND PRODUCE SOMETHING WORKING 10/92 — BulgariaPHP 2019 | @specter_bg

Slide 11

Slide 11 text

BUT NOW YOU NEED TO CHANGE SOMETHING 11/92 — BulgariaPHP 2019 | @specter_bg

Slide 12

Slide 12 text

SOUNDS FAMILIAR? 12/92 — BulgariaPHP 2019 | @specter_bg

Slide 13

Slide 13 text

GET /SPEAKERS/BOYAN > Boyan Yordanov > Ranting at @specter_bg > PHP Varna and VarnaJS organizer > VarnaLab member > always at the NomadPHP meetups 13/92 — BulgariaPHP 2019 | @specter_bg

Slide 14

Slide 14 text

The backend developers said they can only return data from one table. — Mobile Developer 14/92 — BulgariaPHP 2019 | @specter_bg

Slide 15

Slide 15 text

The frontend devs want unrelated data. We'll just return everything. -- Backend Developers 15/92 — BulgariaPHP 2019 | @specter_bg

Slide 16

Slide 16 text

This response is so bloated, we don’t need half of the data. Let’s just use GraphQL. — Front-end / Mobile Developers 16/92 — BulgariaPHP 2019 | @specter_bg

Slide 17

Slide 17 text

17/92 — BulgariaPHP 2019 | @specter_bg

Slide 18

Slide 18 text

COMMON PROBLEMS 18/92 — BulgariaPHP 2019 | @specter_bg

Slide 19

Slide 19 text

> Endpoints change or disappear > Clients are out of date > Parameters switch types > clients constantly wait for the API > documentation and code don't match 19/92 — BulgariaPHP 2019 | @specter_bg

Slide 20

Slide 20 text

OUR PROCESS HAS FAILED US 20/92 — BulgariaPHP 2019 | @specter_bg

Slide 21

Slide 21 text

1. LITTLE UPFRONT DESIGN WORK 21/92 — BulgariaPHP 2019 | @specter_bg

Slide 22

Slide 22 text

2. UNANNOUNCED OR MISCOMMUNICATED CHANGES 22/92 — BulgariaPHP 2019 | @specter_bg

Slide 23

Slide 23 text

WASTE 23/92 — BulgariaPHP 2019 | @specter_bg

Slide 24

Slide 24 text

FRUSTRATION 24/92 — BulgariaPHP 2019 | @specter_bg

Slide 25

Slide 25 text

MORE MEETINGS 25/92 — BulgariaPHP 2019 | @specter_bg

Slide 26

Slide 26 text

WHAT CAN WE DO? 26/92 — BulgariaPHP 2019 | @specter_bg

Slide 27

Slide 27 text

Weeks of coding can save you hours of planning! — unknown 27/92 — BulgariaPHP 2019 | @specter_bg

Slide 28

Slide 28 text

THE PROCESS 2 1. Plan / Design 2. Gather feedback 3. Improve the design 4. Implement the code 5. Verify the implementation 2 Learn more: apisyouwonthate.com/blog/api-design-first-vs-code-first 28/92 — BulgariaPHP 2019 | @specter_bg

Slide 29

Slide 29 text

ITERATE 29/92 — BulgariaPHP 2019 | @specter_bg

Slide 30

Slide 30 text

DESIGN IS NOT A ONE TIME EVENT. 30/92 — BulgariaPHP 2019 | @specter_bg

Slide 31

Slide 31 text

REPEAT THE PROCESS FOR EVERY CHANGE. 31/92 — BulgariaPHP 2019 | @specter_bg

Slide 32

Slide 32 text

PLANNING / DESIGN 32/92 — BulgariaPHP 2019 | @specter_bg

Slide 33

Slide 33 text

33/92 — BulgariaPHP 2019 | @specter_bg

Slide 34

Slide 34 text

API SPECIFICATIONS 34/92 — BulgariaPHP 2019 | @specter_bg

Slide 35

Slide 35 text

A CONTRACT BETWEEN THE API AND ITS USERS 35/92 — BulgariaPHP 2019 | @specter_bg

Slide 36

Slide 36 text

CHOOSE THE RIGHT ONE FOR YOU > OpenAPI > RAML > API Blueprint 36/92 — BulgariaPHP 2019 | @specter_bg

Slide 37

Slide 37 text

37/92 — BulgariaPHP 2019 | @specter_bg

Slide 38

Slide 38 text

FORMERLY KNOWN AS SWAGGER 38/92 — BulgariaPHP 2019 | @specter_bg

Slide 39

Slide 39 text

FORMERLY KNOWN AS SWAGGER 39/92 — BulgariaPHP 2019 | @specter_bg

Slide 40

Slide 40 text

OpenAPI 40/92 — BulgariaPHP 2019 | @specter_bg

Slide 41

Slide 41 text

ABOUT THE SPEC > has lots of tools > yaml or json based > very active community > widely adopted 41/92 — BulgariaPHP 2019 | @specter_bg

Slide 42

Slide 42 text

WRITE BY HAND OR USE A GUI? 42/92 — BulgariaPHP 2019 | @specter_bg

Slide 43

Slide 43 text

OPENAPI CRASH COURSE 43/92 — BulgariaPHP 2019 | @specter_bg

Slide 44

Slide 44 text

READ THE SPEC AT HTTPS://SPEC.OPENAPIS.ORG/OAS/V3.0.2 44/92 — BulgariaPHP 2019 | @specter_bg

Slide 45

Slide 45 text

BASIC STRUCTURE openapi: “3.0.0” info: # ... servers: # ... paths: # ... tags: # ... components: # ... 45/92 — BulgariaPHP 2019 | @specter_bg

Slide 46

Slide 46 text

BASIC INFORMATION ABOUT THE API info: description: >- *Imaginary* free API for managing meetups. Imagined for this **BG PHP 2019** talk. version: '0.1' title: Not The Meetup API contact: email: [email protected] name: Boyan Yordanov url: 'https://boyanyordanov.com' license: # ... 46/92 — BulgariaPHP 2019 | @specter_bg

Slide 47

Slide 47 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 47/92 — BulgariaPHP 2019 | @specter_bg

Slide 48

Slide 48 text

WHAT CAN THE API DO paths: /meetups # ... /meetups/{id} # ... /meetups/{id}/events # ... 48/92 — BulgariaPHP 2019 | @specter_bg

Slide 49

Slide 49 text

A path description /meetups: parameters: # .. get: # ... post: # .. delete: # .. 49/92 — BulgariaPHP 2019 | @specter_bg

Slide 50

Slide 50 text

DESCRIBING PARAMETERS /meetups: # ... parameters: - name: city in: query / path / header / cookie description: Filter meetups based on city schema: type: string 50/92 — BulgariaPHP 2019 | @specter_bg

Slide 51

Slide 51 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 51/92 — BulgariaPHP 2019 | @specter_bg

Slide 52

Slide 52 text

OPERATIONS get: operationId: findMeetups summary: Find Meetups description: Find and search for meetups tags: - meetups parameters: # ,.. responses: # ... 52/92 — BulgariaPHP 2019 | @specter_bg

Slide 53

Slide 53 text

POSSIBLE RESPONSES /meetups/{id} get: responses: '200': content: application/json: schema: # ... '404': content: application/problem+json: # ... 53/92 — BulgariaPHP 2019 | @specter_bg

Slide 54

Slide 54 text

HEADERS headers: RateLimit-Limit: description: The number of allowed requests in the current period schema: type: integer 54/92 — BulgariaPHP 2019 | @specter_bg

Slide 55

Slide 55 text

SCHEMA OBJECTS > based on JSON-Schema draft 4 with some things added and some taken out > support references 55/92 — BulgariaPHP 2019 | @specter_bg

Slide 56

Slide 56 text

EXAMPLE SCHEMA schema: type: object properties: id: type: string format: uuid name: type: string starting-date: type: string format: date 56/92 — BulgariaPHP 2019 | @specter_bg

Slide 57

Slide 57 text

NULLABLE FIELDS city: description: either a string or null type: string nullable: true 57/92 — BulgariaPHP 2019 | @specter_bg

Slide 58

Slide 58 text

OTHER FEATURES > Security schemes > callbacks (and webhooks hopefully soon) 3 > Links (design time only) 3 apisyouwonthate.com/blog/openapi-callbacks-and-webhooks 58/92 — BulgariaPHP 2019 | @specter_bg

Slide 59

Slide 59 text

OPENAPI 3.1 59/92 — BulgariaPHP 2019 | @specter_bg

Slide 60

Slide 60 text

EDITORS WHAT TO LOOK FOR > it should understand YAML > validate the spec > provide some auto-complete > docs preview (not essential) 60/92 — BulgariaPHP 2019 | @specter_bg

Slide 61

Slide 61 text

OPTIONS > Anything with YAML syntax highlighting > Visual Studio Code with openapi-lint extension ❤ > IntelliJ IDE + Senya editor (paid) > Swagger Editor 61/92 — BulgariaPHP 2019 | @specter_bg

Slide 62

Slide 62 text

GUI EDITORS 62/92 — BulgariaPHP 2019 | @specter_bg

Slide 63

Slide 63 text

WHY? > no need to fully understand the spec > can be faster to work > can be used by non-developers 63/92 — BulgariaPHP 2019 | @specter_bg

Slide 64

Slide 64 text

STOPLIGHT STUDIO 4 > Fully supports OAS 2 and 3 > Integrated linting via Spectral > Integrated mock server - Prism > Git integration > Docs including Markdown files 4 BeachCasts Video about Studio: youtube.com/watch?v=ZgYh7HwTJDE 64/92 — BulgariaPHP 2019 | @specter_bg

Slide 65

Slide 65 text

65/92 — BulgariaPHP 2019 | @specter_bg

Slide 66

Slide 66 text

GATHER FEEDBACK 66/92 — BulgariaPHP 2019 | @specter_bg

Slide 67

Slide 67 text

DOCUMENTATION 67/92 — BulgariaPHP 2019 | @specter_bg

Slide 68

Slide 68 text

OPTIONS > ReDoc > Swagger UI (hosted option) > Stoplight Hosted 68/92 — BulgariaPHP 2019 | @specter_bg

Slide 69

Slide 69 text

69/92 — BulgariaPHP 2019 | @specter_bg

Slide 70

Slide 70 text

MOCK API GATHER FEEDBACK 70/92 — BulgariaPHP 2019 | @specter_bg

Slide 71

Slide 71 text

71/92 — BulgariaPHP 2019 | @specter_bg

Slide 72

Slide 72 text

OPTIONS > Prism > API Sprout > SwaggerHub > Roll your own 72/92 — BulgariaPHP 2019 | @specter_bg

Slide 73

Slide 73 text

PRISM > npm install -g @stoplight/prism-cli` > prism mock -d openapi.yaml { "data": { "id": "d8bb3694-9bee-434c-ce95-c9b368a87387", "name": "PHP Varna", "city": "Jenkinsmouth", "starting-date": "1982-04-21", "country": "Panama" } } 73/92 — BulgariaPHP 2019 | @specter_bg

Slide 74

Slide 74 text

IMPROVE THE DESIGN 74/92 — BulgariaPHP 2019 | @specter_bg

Slide 75

Slide 75 text

> Keep the spec in version control > Lint it in CI > Review changes in PRs > Regenerate docs, mocks server, tests 75/92 — BulgariaPHP 2019 | @specter_bg

Slide 76

Slide 76 text

IMPLEMENTATION 76/92 — BulgariaPHP 2019 | @specter_bg

Slide 77

Slide 77 text

CODE GENERATION 77/92 — BulgariaPHP 2019 | @specter_bg

Slide 78

Slide 78 text

OPENAPI-GENERATOR > generate server stubs > generate clients > custom generators > some generators might be out of date 78/92 — BulgariaPHP 2019 | @specter_bg

Slide 79

Slide 79 text

JANE PHP > generates better php clients > supports OpenAPI v3 and json-schema > based on PSR-7 and PSR-18 79/92 — BulgariaPHP 2019 | @specter_bg

Slide 80

Slide 80 text

VALIDATION 80/92 — BulgariaPHP 2019 | @specter_bg

Slide 81

Slide 81 text

THEPHPLEAGUE/OPENAPI-PSR7-VALIDATOR > new package from the PHP League > PSR-7 requests and response validation > PSR-15 middleware 81/92 — BulgariaPHP 2019 | @specter_bg

Slide 82

Slide 82 text

TESTING 82/92 — BulgariaPHP 2019 | @specter_bg

Slide 83

Slide 83 text

MANUAL TESTING 83/92 — BulgariaPHP 2019 | @specter_bg

Slide 84

Slide 84 text

POSTMAN > Direct OpenAPI import trough GUI > Import with Postman API 84/92 — BulgariaPHP 2019 | @specter_bg

Slide 85

Slide 85 text

AUTOMATED TESTS 85/92 — BulgariaPHP 2019 | @specter_bg

Slide 86

Slide 86 text

ROLL YOUR OWN ENHANCE YOUR FUNCTIONAL/INTEGRATION TESTS > extract response schemas from the spec > make a request > validate the response with a validation library 86/92 — BulgariaPHP 2019 | @specter_bg

Slide 87

Slide 87 text

IF YOU NEED MORE TOOLS OPENAPI.TOOLS! SAY THANKS TO MATT TRASK AND PHIL STURGEON! 87/92 — BulgariaPHP 2019 | @specter_bg

Slide 88

Slide 88 text

REPEAT 88/92 — BulgariaPHP 2019 | @specter_bg

Slide 89

Slide 89 text

BUILD SOMETHING AWESOME 89/92 — BulgariaPHP 2019 | @specter_bg

Slide 90

Slide 90 text

THANK YOU! 90/92 — BulgariaPHP 2019 | @specter_bg

Slide 91

Slide 91 text

QUESTIONS? 91/92 — BulgariaPHP 2019 | @specter_bg

Slide 92

Slide 92 text

RESOURCES > Specification: spec.openapis.org/oas/v3.0.2 > 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/ 92/92 — BulgariaPHP 2019 | @specter_bg