REST API edge cases - Speaker Deck

Slide 1

Slide 1 text

REST API edge cases Soft-deletes, likes/stars/tags

Slide 2

Slide 2 text

Hi, my name is Hannes.

Slide 3

Slide 3 text

laravel

Slide 4

Slide 4 text

mongodb

Slide 5

Slide 5 text

couchdb

Slide 6

Slide 6 text

madewithlove

Slide 7

Slide 7 text

• Developer • Laravel since 4.0.0-BETA2 • madewithlove ABOUT ME

Slide 8

Slide 8 text

REST API

Slide 9

Slide 9 text

A Github user stars a repository

Slide 10

Slide 10 text

STAR /repos/username/repo…

Slide 11

Slide 11 text

A user archives an email

Slide 12

Slide 12 text

ARCHIVE /emails/159803922

Slide 13

Slide 13 text

UNARCHIVE /emails/159803922

Slide 14

Slide 14 text

• REST basics • Case study • How it’s done REST API FOR LIKES

Slide 15

Slide 15 text

1. REST basics

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

REST BASICS - SOAP POST /SomeService.aspx Host: example.org

Slide 18

Slide 18 text

REST BASICS - SOAP IBM

Slide 19

Slide 19 text

REST BASICS - REST EQUIVALENT GET /stocks/ibm HTTP/1.1 Host: example.org Accept: application/xml

Slide 20

Slide 20 text

CRUD - HTTP verbs

Slide 21

Slide 21 text

REST BASICS - HTTP METHOD - CREATE Create: POST

Slide 22

Slide 22 text

REST BASICS - HTTP METHODS - CREATE POST /notes HTTP/1.1 Host: example.org

Slide 23

Slide 23 text

REST BASICS - HTTP METHODS - CREATE Create: POST or PUT

Slide 24

Slide 24 text

REST BASICS - HTTP METHODS - CREATE PUT /notes/meeting1-report HTTP/1.1 Host: example.org

Slide 25

Slide 25 text

REST BASICS - HTTP METHODS - READ Read: GET

Slide 26

Slide 26 text

REST BASICS - HTTP METHODS - READ GET /users/driesvints HTTP/1.1 Host: api.github.com HTTP/1.1 200 OK

Slide 27

Slide 27 text

REST BASICS - HTTP METHODS - UPDATE Update: PUT

Slide 28

Slide 28 text

REST BASICS - HTTP METHODS - UPDATE PUT /users/driesvints HTTP/1.1 Host: api.github.com { "login": "driesvints", "id": 594614, "avatar_url": "https://avatars.gith…", "email": "[email protected]", …

Slide 29

Slide 29 text

REST BASICS - HTTP METHODS - UPDATE Update: PUT or PATCH

Slide 30

Slide 30 text

REST BASICS - HTTP METHODS - UPDATE PATCH /users/driesvints HTTP/1.1 Host: api.github.com [email protected]

Slide 31

Slide 31 text

REST BASICS - HTTP METHODS - DELETE Delete: DELETE

Slide 32

Slide 32 text

REST BASICS - HTTP METHODS - DELETE DELETE /repos/driesvints/docs HTTP/1.1 Host: api.github.com HTTP/1.1 204 No Content

Slide 33

Slide 33 text

Headers

Slide 34

Slide 34 text

/followers/ids.json REST BASICS - HTTP HEADERS - CONTENT TYPE

Slide 35

Slide 35 text

REST BASICS - HTTP HEADERS - CONTENT TYPE Accept: application/json

Slide 36

Slide 36 text

https://api.twitter.com/1.0/ https://api.twitter.com/1.1/ REST BASICS - HTTP HEADERS - VERSION

Slide 37

Slide 37 text

Accept: application/vnd.github.v3+json REST BASICS - HTTP HEADERS - VERSION

Slide 38

Slide 38 text

REST BASICS - HTTP HEADERS - AUTHENTICATION https://api.instagram.com/v1/users/ self?access_token=r4nd0m0123456789

Slide 39

Slide 39 text

GET /users/driesvints HTTP/1.1 Host: api.github.com Authorization: Bearer r4nd0m0123456789 REST BASICS - HTTP HEADERS - AUTHENTICATION

Slide 40

Slide 40 text

REST BASICS - HTTP HEADERS - RATE LIMIT https://api.twitter.com/1.1/ application/rate_limit_status.json

Slide 41

Slide 41 text

REST BASICS - HTTP HEADERS - RATE LIMIT - GH HTTP/1.1 403 Forbidden X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1377013266

Slide 42

Slide 42 text

REST BASICS - HTTP HEADERS - RATE LIMIT HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1377013266

Slide 43

Slide 43 text

HTTP/1.1 429 Too Many Requests X-RateLimit-UserLimit: 60 X-RateLimit-UserRemaining: 0 X-RateLimit-UserReset: 1377… REST BASICS - HTTP HEADERS - RATE LIMIT

Slide 44

Slide 44 text

HTTP/1.1 429 Too Many Requests X-RateLimit-ClientLimit: 60 X-RateLimit-ClientRemaining: 0 X-RateLimit-ClientReset: 1377… REST BASICS - HTTP HEADERS - RATE LIMIT

Slide 45

Slide 45 text

URL scheme

Slide 46

Slide 46 text

REST BASICS - URL SCHEME Required params = URL segments

Slide 47

Slide 47 text

REST BASICS - URL SCHEME Optional params = GET params

Slide 48

Slide 48 text

REST BASICS - URL SCHEME /orgs/{org_slug}/report/ {start_date}/{end_date}

Slide 49

Slide 49 text

REST BASICS - URL SCHEME /orgs/mwl/report/ 2014-01-01/2014-06-30

Slide 50

Slide 50 text

REST BASICS - URL SCHEME /orgs/mwl/report ?start_date=2014-01-01 &end_date=2014-06-30

Slide 51

Slide 51 text

REST BASICS - RECAP • HTTP Verbs • HTTP Headers • Required vs. Optional

Slide 52

Slide 52 text

2. Case study

Slide 53

Slide 53 text

CASE STUDY - TWITTER Twitter favorites

Slide 54

Slide 54 text

CASE STUDY - TWITTER - FAVORITED? GET /1.1/statuses/show/51673… HTTP/1.1 Host: api.twitter.com { "favorited": true, …

Slide 55

Slide 55 text

CASE STUDY - TWITTER - FAVORITE POST /1.1/favorites/create.json?id=51673… HTTP/1.1 Host: api.twitter.com

Slide 56

Slide 56 text

CASE STUDY - TWITTER - UNFAVORITE POST /1.1/favorites/destroy.json?id=51673… HTTP/1.1 Host: api.twitter.com

Slide 57

Slide 57 text

CASE STUDY - GITHUB Github stargazers

Slide 58

Slide 58 text

CASE STUDY - GITHUB - STARRED? GET /user/starred/:owner/:repo HTTP/1.1 Host: api.github.com HTTP/1.1 204 No Content HTTP/1.1 404 Not found

Slide 59

Slide 59 text

CASE STUDY - GITHUB - STAR PUT /user/starred/:owner/:repo HTTP/1.1 Host: api.github.com HTTP/1.1 204 No Content

Slide 60

Slide 60 text

CASE STUDY - GITHUB - UNSTAR DELETE /user/starred/:owner/:repo HTTP/1.1 Host: api.github.com HTTP/1.1 204 No Content

Slide 61

Slide 61 text

CASE STUDY - FOURSQUARE Foursquare likes

Slide 62

Slide 62 text

CASE STUDY - FOURSQUARE - LIKED? GET /v2/venues/4b292… HTTP/1.1 Host: api.foursquare.com { "like": true, …

Slide 63

Slide 63 text

CASE STUDY - FOURSQUARE - LIKED? GET /v2/venues/4b292… HTTP/1.1 Host: api.foursquare.com { "dislike": true, …

Slide 64

Slide 64 text

CASE STUDY - FOURSQUARE - LIKE POST /v2/venues/4b292…/like HTTP/1.1 Host: api.foursquare.com set=1

Slide 65

Slide 65 text

CASE STUDY - FOURSQUARE - UNLIKE POST /v2/venues/4b292…/like HTTP/1.1 Host: api.foursquare.com set=0

Slide 66

Slide 66 text

CASE STUDY - FOURSQUARE - LIKE POST /v2/checkins/4b292…/like HTTP/1.1 Host: api.foursquare.com set=1

Slide 67

Slide 67 text

CASE STUDY - FOURSQUARE - UNLIKE POST /v2/checkins/4b292…/like HTTP/1.1 Host: api.foursquare.com set=0

Slide 68

Slide 68 text

CASE STUDY - INSTAGRAM Instagram likes

Slide 69

Slide 69 text

CASE STUDY - INSTAGRAM - LIKED? GET /v1/media/4b292…/likes HTTP/1.1 Host: api.instagram.com { "data": [ { "username": "gilbert_west", "id": "586708382", …

Slide 70

Slide 70 text

CASE STUDY - INSTAGRAM - LIKE POST /v1/media/4b292…/likes HTTP/1.1 Host: api.instagram.com

Slide 71

Slide 71 text

CASE STUDY - INSTAGRAM - UNLIKE DELETE /v1/media/4b292…/likes HTTP/1.1 Host: api.instagram.com

Slide 72

Slide 72 text

3. How it’s done

Slide 73

Slide 73 text

In my opinion

Slide 74

Slide 74 text

Github + Instagram HOW IT’S DONE - LIKES

Slide 75

Slide 75 text

HOW IT’S DONE - LIKES - LIKED? GET /notes/{id} HTTP/1.1 Host: example.org { "liked": true, …

Slide 76

Slide 76 text

HOW IT’S DONE - LIKES - PEOPLE WHO LIKED GET /notes/{id}/likes HTTP/1.1 Host: example.org

Slide 77

Slide 77 text

HOW IT’S DONE - LIKES - LIKE PATCH /notes/{id} HTTP/1.1 Host: example.org liked=true

Slide 78

Slide 78 text

HOW IT’S DONE - LIKES - UNLIKE PATCH /notes/{id} HTTP/1.1 Host: example.org liked=false

Slide 79

Slide 79 text

Soft delete? DELETE /endpoint

Slide 80

Slide 80 text

HOW IT’S DONE - SOFT DELETE DELETE /notes/1234 HTTP/1.1 Host: example.org

Slide 81

Slide 81 text

HOW IT’S DONE - SOFT DELETE GET /deleted_notes HTTP/1.1 Host: example.org

Slide 82

Slide 82 text

HOW IT’S DONE - SOFT DELETE PATCH /deleted_notes/1234 HTTP/1.1 Host: example.org deleted=false

Slide 83

Slide 83 text

Archiving?

Slide 84

Slide 84 text

HOW IT’S DONE - ARCHIVING PATCH /notes/1234 HTTP/1.1 Host: example.org archived=true

Slide 85

Slide 85 text

HOW IT’S DONE - ARCHIVING GET /archived_notes HTTP/1.1 Host: example.org

Slide 86

Slide 86 text

HOW IT’S DONE - ARCHIVING PATCH /archived_notes/1234 HTTP/1.1 Host: example.org archived=false

Slide 87

Slide 87 text

• Likes • Soft deletes • Archiving RECAP - EDGE CASES

Slide 88

Slide 88 text

• REST basics • Case study • How it’s done RECAP

Slide 89

Slide 89 text

No content

Slide 90

Slide 90 text

No content

Slide 91

Slide 91 text

Questions/discussions

Slide 92

Slide 92 text

Thank you! @hannesvdvreken

Slide 93

Slide 93 text

• http:/ /wikipedia.org/wiki/SOAP • http:/ /meetup.com/mongodb-belgium • http:/ /mwl.be • http:/ /shop.oreilly.com/product/0636920028468.do • https:/ /leanpub.com/build-apis-you-wont-hate • https:/ /dev.twitter.com • http:/ /instagram.com/developer • https:/ /developer.github.com • https:/ /developer.foursquare.com REFERENCES