Slide 1

Slide 1 text

© 2022Cisco and/or its affiliates. All rightsreserved. Cisco Confidential. Marcel Neidinger Software Solutions Engineer, EMEA Systems Engineering 18.10.2022 Develop | Oct 18th API Nightmares Building the worst API possible – so you don’t have to

Slide 2

Slide 2 text

@squ4rks

Slide 3

Slide 3 text

Let’s make those endpoints hurt.

Slide 4

Slide 4 text

A reasonable request and response GET /api/v1/users?country=Germany { "id": 1, "firstName": "Max", "lastName": "Musterman", "username": "c1sc0f4n", "address": { "street": "Mainstreet 42C" "city": "Berlin", "country": "Germany" }, "phone": { "mobile": "+49 102 093920", "home": None } }

Slide 5

Slide 5 text

A reasonable request and response { "id": 1, "firstName": "Max", "lastName": "Musterman", "username": "c1sc0f4n", "address": { "street": "Mainstreet 42C" "city": "Berlin", "country": "Germany" }, "phone": { "mobile": "+49 102 093920", "home": None } } GET /api/v1/users?country=Germany

Slide 6

Slide 6 text

Searching is listing and iterating. And it’s best done on the client. Lesson learned

Slide 7

Slide 7 text

Your database (maybe) User id: INTEGER NOT NULL firstName: VARCHAR lastName: VARCHAR username: VARCHAR address: INTEGER[FK] phone: INTEGER[FK] Address id: INTEGER NOT NULL street: VARCHAR city: VARCHAR country: VARCHAR Phone id: INTEGER NOT NULL home: VARCHAR mobile: VARCHAR

Slide 8

Slide 8 text

Less reasonable { "id": 1, "firstName": "Max", "lastName": "Musterman", "username": "c1sc0f4n", "address": 2, "phone": 3 } GET /api/v1/phones GET /api/v1/addresses GET /api/v1/users

Slide 9

Slide 9 text

Don’t give the interface what it needs. Give it your database layout. Lesson learned

Slide 10

Slide 10 text

Less reasonable { "id": 1, "firstName": "Max", "LastName": "Musterman", "user_name": "c1sc0f4n", "address": 2, "phone": 3 } GET /api/v1/phones GET /api/v1/addresses GET /api/v1/users

Slide 11

Slide 11 text

Less reasonable { "id": 1, "firstName": "Max", "LastName": "Musterman", "user_name": "c1sc0f4n", "address": 2, "phone": 3, "enableUser": true, "enabledCalling": false } GET /api/v1/phones GET /api/v1/addresses GET /api/v1/users

Slide 12

Slide 12 text

Less reasonable { "id": 1, "firstName": "Max", "LastName": "Musterman", "user_name": "c1sc0f4n", "address": 2, "phone": 3, "enableUser": true, "enabledCalling": false } GET /api/v1/phone_number GET /api/v1/addresses GET /api/v1/userProfile

Slide 13

Slide 13 text

Inconsistency is the key to bad API design. Apply it to attributes, endpoints and everything inbetween. Lesson learned

Slide 14

Slide 14 text

Less reasonable { "id": 1, […] "address": 2, "phone": 3, "links": [{ "href": "/addresses/2", "rel": "address", "type": "GET" }] } GET /api/v1/phone_number GET /api/v1/addresses GET /api/v1/userProfile

Slide 15

Slide 15 text

Less reasonable { "id": 1, […] "address": 2, "phone": 3, "links": [{ "href": "/addresses/2", "rel": "address", "type": "GET" }] } GET /api/v1/phone_number GET /api/v1/addresses GET /api/v1/userProfile

Slide 16

Slide 16 text

Less reasonable { "id": 1, […] "address": 2, "phone": 3, "links": [{ "path": "/addresses/2", "rel": "address" }] } GET /api/v1/phone_number GET /api/v1/addresses GET /api/v1/userProfile

Slide 17

Slide 17 text

HATEOAS is for people who build usable APIs. Don’t do it. Lesson learned

Slide 18

Slide 18 text

Keywords matter POST /api/v1/userProfile GET /api/v1/userProfile/1 GET /api/v1/userProfile PATCH /api/v1/userProfile/1 DELETE /api/v1/userProfile/1 POST /api/v1/userProfile/1/promote

Slide 19

Slide 19 text

Keywords don’t matter POST /api/v1/userProfile

Slide 20

Slide 20 text

Keywords don’t matter POST /api/v1/userProfile?id=1

Slide 21

Slide 21 text

Keywords don’t matter POST /api/v1/userProfile?id=1&action=delete

Slide 22

Slide 22 text

If we really want it - Everything can be a POST. Lesson learned

Slide 23

Slide 23 text

Who needs errors anyways.

Slide 24

Slide 24 text

A succesfull response HTTP/1.1 200 OK { "id": 2, "firstName": "Max", "LastName": "Musterman", [.. ] } POST /api/v1/userProfiles?action=create

Slide 25

Slide 25 text

A succesfull response HTTP/1.1 400 BAD REQUEST { "error": { "code": 1000, "message": "Field ‘username’ is required", "tracking": "ROUTER_ Pp8q5d" } } POST /api/v1/userProfiles?action=create

Slide 26

Slide 26 text

Also a succesfull response HTTP/1.1 200 OK { "error": { "code": 1000, "message": "Field ‘username’ is required", "tracking": "ROUTER_ Pp8q5d" } } POST /api/v1/userProfiles?action=create

Slide 27

Slide 27 text

Status codes are bad. Always fail succesfully. Lesson learned

Slide 28

Slide 28 text

Also a succesfull response HTTP/1.1 200 OK { "error": { "code": 1000, "message": "Field ‘username’ is required", "tracking": "ROUTER_ Pp8q5d" } } POST /api/v1/userProfiles?action=create

Slide 29

Slide 29 text

Error codes are bad. Always fail without a way to identify the cause. Lesson learned

Slide 30

Slide 30 text

Also a succesfull response HTTP/1.1 200 OK { "error": { "message": "Wrong request", "tracking": "ROUTER_ Pp8q5d" } } POST /api/v1/userProfiles?action=create

Slide 31

Slide 31 text

Keeping your errors as generic as possible saves you time in development. Lesson learned

Slide 32

Slide 32 text

Also a succesfull response HTTP/1.1 200 OK { "error": { "message": "Wrong request", "tracking": "ROUTER_ Pp8q5d" } } POST /api/v1/userProfiles?action=create

Slide 33

Slide 33 text

Tracking codes make it easy to find logs. What’s the fun in easy? Lesson learned

Slide 34

Slide 34 text

I know a limit that you don’t.

Slide 35

Slide 35 text

On your API docs Rate Limiting Rate Limiting is required to maintain proper service levels for all users of our platform. Handling rate-limited requests If you hit a rate limit a 429 Too Many Requests status will be send. The response also has a Retry-After header with your wait time in seconds.

Slide 36

Slide 36 text

A succesfull response HTTP/1.1 429 TOO MANY REQUESTS Retry-After: 20 { } POST /api/v1/userProfiles?action=create

Slide 37

Slide 37 text

A succesfull response HTTP/1.1 200 OK Retry-After: 20 { "error": { "message": "Too much" } } POST /api/v1/userProfiles?action=create

Slide 38

Slide 38 text

A succesfull response HTTP/1.1 200 OK Retry-After: 20 { "error": { "message": "Too much" } } POST /api/v1/userProfiles?action=create

Slide 39

Slide 39 text

On your API docs Rate Limiting Rate Limiting is required to maintain proper service levels for all users of our platform. Handling rate-limited requests If you hit a rate limit a 429 Too Many Requests status will be send. The response also has a Retry-After header with your wait time in seconds.

Slide 40

Slide 40 text

There is beauty in opaque numbers. Why tell the user how long to wait for? Lesson learned

Slide 41

Slide 41 text

On your API docs Rate Limiting […] Upper Limits You can expect the following upper limits (with some leway to burst requests): - Maximum of 100 requests per minute - Maximum of 60 requests for POST /userProfiles

Slide 42

Slide 42 text

On your API docs Rate Limiting […] Upper Limits You can expect the following upper limits (with some leway to burst requests): - Maximum of 100 requests per minute - Maximum of 60 requests for POST /userProfiles

Slide 43

Slide 43 text

Consistently inconsistent is the way to go for our rate limit. Lesson learned

Slide 44

Slide 44 text

A succesfull response HTTP/1.1 200 OK { "error": { "message": "Bad user" } } POST /api/v1/userProfiles?action=create

Slide 45

Slide 45 text

Be draconic. It’s driving up your bill afterall. Lesson learned

Slide 46

Slide 46 text

In terms of docs, we have no docs.

Slide 47

Slide 47 text

The best doc is no doc. Lesson learned

Slide 48

Slide 48 text

On your API docs User Profiles POST userProfiles?action=details&id= Response Properties: - username: The username - firstName: The first name

Slide 49

Slide 49 text

Standards are there to be broken. Run your own! What’s a "swagger" anyway? Lesson learned

Slide 50

Slide 50 text

On your API docs User Profiles POST userProfiles?action=details&id= Response Properties: - username: The username - firstName: The first name

Slide 51

Slide 51 text

Don’t generate your docs from code (or vice versa). That would make them consistent. Lesson learned

Slide 52

Slide 52 text

On your API docs Changelog August 22, 2022 • The userProfile endpoint now returns the username field as user_name. • The API now offers a promote action on user profiles. Breaking Change New Subscribe via RSS Subscribe via e-mail

Slide 53

Slide 53 text

On your companies social media feed Marcel Neidinger @squ4rks @ACMEInc did you change the username attribute for a user profile to user_name?!? Today at 03:42am

Slide 54

Slide 54 text

Use error-driven changelogs for your API. Lesson learned

Slide 55

Slide 55 text

Sanity.

Slide 56

Slide 56 text

Consistency

Slide 57

Slide 57 text

Predictability

Slide 58

Slide 58 text

No content

Slide 59

Slide 59 text

No content