Creating Solid APIs - PyCon Estonia 2018

Slide 1

Slide 1 text

Creating Solid APIs PyCon Estonia 2018 Rivo Laks ⋅ 2018-10-04

Slide 2

Slide 2 text

Background

Slide 3

Slide 3 text

What is an API?

Slide 4

Slide 4 text

What is an API? application programming interface

Slide 5

Slide 5 text

What is an API? application programming interface application programmer interface

Slide 6

Slide 6 text

What is an API? application programming interface application programmer interface API is user interface for developers

Slide 7

Slide 7 text

Goals

Slide 8

Slide 8 text

Goals

Slide 9

Slide 9 text

Goals Comprehensive API for 3rd-party devs

Slide 10

Slide 10 text

Goals Comprehensive API for 3rd-party devs Easy & automated onboarding

Slide 11

Slide 11 text

Goals Comprehensive API for 3rd-party devs Easy & automated onboarding Minimize pain (friction)

Slide 12

Slide 12 text

Versioning

Slide 13

Slide 13 text

Why Do We Need Versioning?

Slide 14

Slide 14 text

Why Do We Need Versioning? for breaking things in controlled fashion

Slide 15

Slide 15 text

How to Version?

Slide 16

Slide 16 text

How to Version? You need: Deprecation schedules

Slide 17

Slide 17 text

How to Version? You need: Deprecation schedules Changelogs / upgrade notes

Slide 18

Slide 18 text

Versioning Schemes

Slide 19

Slide 19 text

Versioning Schemes Using Accept header GET /projects HTTP/1.0 Accept: application/json; version=1

Slide 20

Slide 20 text

Versioning Schemes Using Accept header GET /projects HTTP/1.0 Accept: application/json; version=1 Using URL path GET /v1/projects HTTP/1.0 Accept: application/json

Slide 21

Slide 21 text

Versioning Schemes Cont. Integers ( v1 ) vs dates ( 2018-10-04 )?

Slide 22

Slide 22 text

Versioning Schemes Cont. Integers ( v1 ) vs dates ( 2018-10-04 )? Dates are less emotional

Slide 23

Slide 23 text

Versioning Schemes Cont. Integers ( v1 ) vs dates ( 2018-10-04 )? Dates are less emotional Easier internal / test versions

Slide 24

Slide 24 text

Version Transformers

Slide 25

Slide 25 text

Version Transformers » » Requests into newer version » » Core code is for latest version « « Responses into older version « «

Slide 26

Slide 26 text

Version Transformers » » Requests into newer version » » Core code is for latest version « « Responses into older version « « Won't work for big, breaking changes

Slide 27

Slide 27 text

Authentication & Authorization

Slide 28

Slide 28 text

Token Authentication Clients send HTTP header, ala Authorization: Token 9944b09199c62bcf9418

Slide 29

Slide 29 text

OAuth 2.0

Slide 30

Slide 30 text

OAuth 2.0 For creating platforms

Slide 31

Slide 31 text

OAuth 2.0 For creating platforms Complex, but solves many issues

Slide 32

Slide 32 text

OAuth 2.0 For creating platforms Complex, but solves many issues Many packages, e.g. Django OAuth Toolkit, OAuthLib

Slide 33

Slide 33 text

Standardize!

Slide 34

Slide 34 text

Standardize! Standards help: bring familiarity

Slide 35

Slide 35 text

Standardize! Standards help: bring familiarity avoid common pitfalls

Slide 36

Slide 36 text

Standardize! Standards help: bring familiarity avoid common pitfalls historically, standardized approaches win

Slide 37

Slide 37 text

JSON API http://jsonapi.org/ one potential standard to use

Slide 38

Slide 38 text

JSON API http://jsonapi.org/ one potential standard to use GraphQL is another option

Slide 39

Slide 39 text

Standardize Structure

Slide 40

Slide 40 text

Standardize Structure Responses have predictable, familiar structure

Slide 41

Slide 41 text

GET https://example.com/api/v1/projects { "links": { "next": "https://example.com/api/v1/projects?cursor=cD0yMDE4L", "prev": null }, "data": [...], "included": [...] }

Slide 42

Slide 42 text

"data": [ { "type": "project", "id": "289", "links": { "self": "https://example.com/api/v1/projects/289" }, "attributes": { "created": "2018-06-28T22:52:08.690486Z", "name": "Allison-Patterson", "description": "aggregate collaborative models" }, "relationships": {...} }, ... ],

Slide 43

Slide 43 text

"data": [{ ... "relationships": { "created_by": { "data": { "type": "user", "id": "199" } }, "epics": { "data": [ { "type": "epic", "id": "3101" } ], } } }, ... ],

Slide 44

Slide 44 text

"included": [ { "type": "epic", "id": "3101", "attributes": { "created": "2018-06-28T22:50:45.885691Z", "name": "Ergonomic background extranet" }, "links": { "self": "https://example.com/api/v1/epics/3101" } }, { "type": "user", "id": "199", "attributes": {...} } ]

Slide 45

Slide 45 text

Impressions?

Slide 46

Slide 46 text

Flexibility Con gurable elds: GET https://example.com/api/v1/projects GET https://example.com/api/v1/projects \ ?included=comments GET https://example.com/api/v1/projects \ ?included=comments&fields[project]=name,comments

Slide 47

Slide 47 text

Errors

Slide 48

Slide 48 text

Errors POST https://example.com/api/v1/projects { "errors": [ { "title": "Invalid Attribute", "detail": "Name must contain at least three letters.", "source": { "pointer": "/data/attributes/name" }, "code": "name_too_short", "status": "422" } ] }

Slide 49

Slide 49 text

Standardization Matters the speci c standard isn't that important GraphQL, etc are also good options

Slide 50

Slide 50 text

Documentation

Slide 51

Slide 51 text

Documentation Often overlooked

Slide 52

Slide 52 text

Documentation Often overlooked Gives the rst impression

Slide 53

Slide 53 text

Documentation Often overlooked Gives the rst impression The e ort is worth it!

Slide 54

Slide 54 text

Creating Awesome Docs

Slide 55

Slide 55 text

What Should Go In There?

Slide 56

Slide 56 text

What Should Go In There? The purpose

Slide 57

Slide 57 text

What Should Go In There? The purpose How do I access it?

Slide 58

Slide 58 text

What Should Go In There? The purpose How do I access it? Do I need developer account?

Slide 59

Slide 59 text

What Should Go In There? The purpose How do I access it? Do I need developer account? Root URL, etc

Slide 60

Slide 60 text

What Should Go In There? The purpose How do I access it? Do I need developer account? Root URL, etc Authentication info

Slide 61

Slide 61 text

What Should Go In There? General encodings, formats, etc

Slide 62

Slide 62 text

What Should Go In There? General encodings, formats, etc Versioning, pagination, etc

Slide 63

Slide 63 text

What Should Go In There? General encodings, formats, etc Versioning, pagination, etc Common errors

Slide 64

Slide 64 text

What Should Go In There? General encodings, formats, etc Versioning, pagination, etc Common errors Code for getting started

Slide 65

Slide 65 text

The Endpoints

Slide 66

Slide 66 text

The Endpoints URL & operations

Slide 67

Slide 67 text

The Endpoints URL & operations Request/response data

Slide 68

Slide 68 text

The Endpoints URL & operations Request/response data Optional parameters

Slide 69

Slide 69 text

The Endpoints URL & operations Request/response data Optional parameters Permissions etc

Slide 70

Slide 70 text

Keep it Fresh!

Slide 71

Slide 71 text

Keep it Fresh! Obsolete docs are the worst

Slide 72

Slide 72 text

Keep it Fresh! Obsolete docs are the worst Always autogenerate!

Slide 73

Slide 73 text

Keep it Fresh! Obsolete docs are the worst Always autogenerate! Usually code » schema » docs

Slide 74

Slide 74 text

Schema & Autogeneration

Slide 75

Slide 75 text

Schema & Autogeneration OpenAPI, Swagger, etc

Slide 76

Slide 76 text

Schema & Autogeneration OpenAPI, Swagger, etc Use your tools

Slide 77

Slide 77 text

Schema & Autogeneration OpenAPI, Swagger, etc Use your tools Combine docs & code examples

Slide 78

Slide 78 text

Schema & Autogeneration OpenAPI, Swagger, etc Use your tools Combine docs & code examples Client libs autogeneration

Slide 79

Slide 79 text

In Summary Embrace standards (e.g. JSON API) Invest in documentation Use automation Reduce friction

Slide 80

Slide 80 text

Thanks! Rivo Laks ⋅ @rivolaks ⋅ rivolaks.com tinyurl.com/PyConEstonia18api