Creating Solid APIs EuroPython 2018 Rivo Laks 2018-07-27 - - PowerPoint PPT Presentation

▶
creating solid apis
SMART_READER_LITE
LIVE PREVIEW

Creating Solid APIs EuroPython 2018 Rivo Laks 2018-07-27 - - PowerPoint PPT Presentation

Aug 29, 2022 117 likes •983 views

Creating Solid APIs EuroPython 2018 Rivo Laks 2018-07-27 Background What is an API? What is an API? application programming interface What is an API? application programming interface application programmer interface What is an API?

slide-1
SLIDE 1

Creating Solid APIs

EuroPython 2018 Rivo Laks ⋅ 2018-07-27

slide-2
SLIDE 2

Background

slide-3
SLIDE 3

What is an API?

slide-4
SLIDE 4

What is an API?

application programming interface

slide-5
SLIDE 5

What is an API?

application programming interface application programmer interface

slide-6
SLIDE 6

What is an API?

application programming interface application programmer interface API is user interface for developers

slide-7
SLIDE 7

What Makes an API Good?

slide-8
SLIDE 8

What Makes an API Good?

Documentation

slide-9
SLIDE 9

What Makes an API Good?

Documentation Familiarity

slide-10
SLIDE 10

What Makes an API Good?

Documentation Familiarity Lack of friction

slide-11
SLIDE 11

Documentation

Often overlooked

slide-12
SLIDE 12

Documentation

Often overlooked Gives the rst impression

slide-13
SLIDE 13

Documentation

Often overlooked Gives the rst impression The eort is worth it!

slide-14
SLIDE 14

Creating Awesome Docs

slide-15
SLIDE 15

What Should Go In There?

slide-16
SLIDE 16

What Should Go In There?

How do I access it?

slide-17
SLIDE 17

What Should Go In There?

How do I access it? Do I need developer account?

slide-18
SLIDE 18

What Should Go In There?

How do I access it? Do I need developer account? Root URL, etc

slide-19
SLIDE 19

What Should Go In There?

How do I access it? Do I need developer account? Root URL, etc Authentication info

slide-20
SLIDE 20

What Should Go In There?

General encodings, formats, etc

slide-21
SLIDE 21

What Should Go In There?

General encodings, formats, etc Pagination, versioning, etc

slide-22
SLIDE 22

What Should Go In There?

General encodings, formats, etc Pagination, versioning, etc Common errors

slide-23
SLIDE 23

What Should Go In There?

General encodings, formats, etc Pagination, versioning, etc Common errors Code for getting started

slide-24
SLIDE 24

The Endpoints

slide-25
SLIDE 25

The Endpoints

URL & operations

slide-26
SLIDE 26

The Endpoints

URL & operations Request/response data

slide-27
SLIDE 27

The Endpoints

URL & operations Request/response data Optional parameters

slide-28
SLIDE 28

The Endpoints

URL & operations Request/response data Optional parameters Permissions etc

slide-29
SLIDE 29

Keep it Fresh!

slide-30
SLIDE 30

Keep it Fresh!

Obsolete docs are the worst

slide-31
SLIDE 31

Keep it Fresh!

Obsolete docs are the worst Always autogenerate!

slide-32
SLIDE 32

Keep it Fresh!

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

slide-33
SLIDE 33

Schema & Autogeneration

slide-34
SLIDE 34

Schema & Autogeneration

OpenAPI, Swagger, etc

slide-35
SLIDE 35

Schema & Autogeneration

OpenAPI, Swagger, etc Use your tools

slide-36
SLIDE 36

Schema & Autogeneration

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

slide-37
SLIDE 37

Schema & Autogeneration

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

slide-38
SLIDE 38

Standardize!

slide-39
SLIDE 39

JSON API

http://jsonapi.org/

  • ne potential standard to use
slide-40
SLIDE 40

JSON API

http://jsonapi.org/

  • ne potential standard to use

GraphQL is another option

slide-41
SLIDE 41

Standardize Structure

slide-42
SLIDE 42

Standardize Structure

Responses have predictable, familiar structure

slide-43
SLIDE 43

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

slide-44
SLIDE 44

"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-45
SLIDE 45

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

slide-46
SLIDE 46

"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-47
SLIDE 47

Impressions?

slide-48
SLIDE 48

Flexibility

Congurable 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-49
SLIDE 49

Pagination

List responses have next / prev links

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

slide-50
SLIDE 50

Pagination

List responses have next / prev links

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

Cursor-based pagination FTW (but YMMV).

slide-51
SLIDE 51

There is More ...

Filtering Ordering

slide-52
SLIDE 52

Errors

slide-53
SLIDE 53

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" }, "status": "422" } ] }

slide-54
SLIDE 54

Special Cases

For when you have LOTS of data

slide-55
SLIDE 55

Special Cases

For when you have LOTS of data

  • ut-of-band approach
slide-56
SLIDE 56

GET https://example.com/api/v1/datasets/123 { "data": { "type": "dataset", "id": "123", "attributes": { "name": "CIFAR10 dataset", }, "links": { "data_tgz": "https://www.cs.toronto.edu/~kriz/cifar-10-python.tar.gz", "self": "https://example.com/api/v1/datasets/123" } } }

slide-57
SLIDE 57

Standardization Matters

the specic standard isn't that important GraphQL, etc are also good options

slide-58
SLIDE 58

Authentication & Authorization

slide-59
SLIDE 59

Token Authentication

Clients send HTTP header, ala

Authorization: Token 9944b09199c62bcf9418

slide-60
SLIDE 60

OAuth 2.0

slide-61
SLIDE 61

OAuth 2.0

For creating platforms

slide-62
SLIDE 62

OAuth 2.0

For creating platforms Complex, but solves many issues

slide-63
SLIDE 63

OAuth 2.0

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

slide-64
SLIDE 64

Versioning

slide-65
SLIDE 65

Versioning Schemes

slide-66
SLIDE 66

Versioning Schemes

AcceptHeaderVersioning (DRF)

GET /projects HTTP/1.0 Accept: application/json; version=1.0

slide-67
SLIDE 67

Versioning Schemes

AcceptHeaderVersioning (DRF)

GET /projects HTTP/1.0 Accept: application/json; version=1.0

URLPathVersioning (DRF)

GET /v1/projects HTTP/1.0 Accept: application/json

slide-68
SLIDE 68

Versioning Schemes Cont.

Integers ( v1 ) vs dates ( 2018-07-27 )?

slide-69
SLIDE 69

Versioning Schemes Cont.

Integers ( v1 ) vs dates ( 2018-07-27 )? Dates are less emotional

slide-70
SLIDE 70

Versioning Schemes Cont.

Integers ( v1 ) vs dates ( 2018-07-27 )? Dates are less emotional Make upgrades easy

slide-71
SLIDE 71

Version Transformers

slide-72
SLIDE 72

Version Transformers

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

slide-73
SLIDE 73

Version Transformers

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

slide-74
SLIDE 74

Client's Perspective

slide-75
SLIDE 75

The Scenario

Let's try speech recognition...

slide-76
SLIDE 76

The Scenario

Let's try speech recognition... ... using AWS and GCP

slide-77
SLIDE 77

Getting Started

Documentation

slide-78
SLIDE 78

Getting Started

Documentation Quite easy to nd A bit overwhelming

slide-79
SLIDE 79

Getting Started

Documentation Quite easy to nd A bit overwhelming Code examples

slide-80
SLIDE 80

Comprehensive Clients

Install Python client GCP: google-cloud package AWS: boto3 package

slide-81
SLIDE 81

Comprehensive Clients

Install Python client GCP: google-cloud package AWS: boto3 package Authenticate

slide-82
SLIDE 82

Comprehensive Clients

Install Python client GCP: google-cloud package AWS: boto3 package Authenticate Thorough docs

slide-83
SLIDE 83

Amazon

import boto3 client = boto3.client('transcribe') response = client.start_transcription_job(...)

slide-84
SLIDE 84

Amazon

import boto3 client = boto3.client('transcribe') response = client.start_transcription_job(...)

Google

from google.cloud import speech client = speech.SpeechClient() results = client.recognize(...)

slide-85
SLIDE 85

In Summary

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

slide-86
SLIDE 86

Thanks!

Rivo Laks ⋅ @rivolaks ⋅ rivolaks.com tinyurl.com/ep18api