Slide 1

Slide 1 text

Radoslav Stankov BlagoevgradConf 2013 30/11/2013 Designing Mobile APIs

Slide 2

Slide 2 text

Radoslav Stankov @rstankov ! ! ! ! http://rstankov.com http://github.com/rstankov

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

I have a plan!

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda

Slide 7

Slide 7 text

Mobile in numbers

Slide 8

Slide 8 text

No content

Slide 9

Slide 9 text

Web App Mobile API

Slide 10

Slide 10 text

Mobile API

Slide 11

Slide 11 text

Example

Slide 12

Slide 12 text

1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda

Slide 13

Slide 13 text

1.Versioning! 2.Headers 3.Error responses 4.Authentication 5.REST Agenda

Slide 14

Slide 14 text

Versioning

Slide 15

Slide 15 text

http://fantasy-football.com/api/v1/team/1.json

Slide 16

Slide 16 text

http://fantasy-football.com/api/v1/team/1.json

Slide 17

Slide 17 text

https://fantasy-football.com/api/v1/team/1.json

Slide 18

Slide 18 text

https://fantasy-football.com/api/v1/team/1.json

Slide 19

Slide 19 text

https://fantasy-football.com/api/v1/team/1.json

Slide 20

Slide 20 text

https://mobile.fantasy-football.com/v1/team/1.json

Slide 21

Slide 21 text

https://mobile.fantasy-football.com/v1/team/1.json

Slide 22

Slide 22 text

https://mobile.fantasy-football.com/v1/team/1.json

Slide 23

Slide 23 text

Content-Types that are acceptable for the response. Accept Header

Slide 24

Slide 24 text

https://mobile.fantasy-football.com/v1/team/1.json

Slide 25

Slide 25 text

Accept: application/json https://mobile.fantasy-football.com/v1/team/1.json

Slide 26

Slide 26 text

Accept: application/json https://mobile.fantasy-football.com/v1/team/1

Slide 27

Slide 27 text

Accept: application/json https://mobile.fantasy-football.com/v1/team/1

Slide 28

Slide 28 text

Accept: application/vnd.football-team.com; version=1, application/json https://mobile.fantasy-football.com/v1/team/1

Slide 29

Slide 29 text

Accept: application/vnd.football-team.com; version=1, application/json https://mobile.fantasy-football.com/team/1

Slide 30

Slide 30 text

1.Versioning! 2.Headers 3.Error responses 4.Authentication 5.REST Agenda

Slide 31

Slide 31 text

1.Versioning 2.Headers! 3.Error responses 4.Authentication 5.REST Agenda

Slide 32

Slide 32 text

Headers

Slide 33

Slide 33 text

User-Agent User-Agent: iOS 7.1

Slide 34

Slide 34 text

Accept-Language Accept-Language: en

Slide 35

Slide 35 text

! • X-Api-Key • X-Push-Notification-Id • X-Checksum • …. Custom

Slide 36

Slide 36 text

! • X-Api-Key • X-Push-Notification-Id • X-Checksum • …. Custom

Slide 37

Slide 37 text

1.Versioning 2.Headers! 3.Error responses 4.Authentication 5.REST Agenda

Slide 38

Slide 38 text

1.Versioning 2.Headers 3.Error responses! 4.Authentication 5.REST Agenda

Slide 39

Slide 39 text

Error responses

Slide 40

Slide 40 text

HTTP Statuses Code Description 400 Bad Request 401 Unauthorized 402 Account Is Locked 404 Not Found 405 Method Not Allowed 422 Unprocessable Entity 426 To Many Requests 500 Internal Server Error

Slide 41

Slide 41 text

HTTP Statuses http://httpstatus.es/

Slide 42

Slide 42 text

Response Body { “message”: “Invalid api key” } GET https://mobile.fantasy-football.com/teams/1

Slide 43

Slide 43 text

422 - Unprocessable Entity { “errors”: {
 “name”: [“Already taken”], “budget”: [“Must be more than 0”] } } POST https://mobile.fantasy-football.com/teams/

Slide 44

Slide 44 text

1.Versioning 2.Headers 3.Error responses! 4.Authentication 5.REST Agenda

Slide 45

Slide 45 text

1.Versioning 2.Headers 3.Error responses 4.Authentication! 5.REST Agenda

Slide 46

Slide 46 text

Authentication

Slide 47

Slide 47 text

WWW-Authentication > WWW-Authenticate: Basic realm=“Fantasy Football” ! < Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Slide 48

Slide 48 text

WWW-Authentication > WWW-Authenticate: Digest realm=“Fantasy Football", … ! < Authorization: Digest username=“User", …

Slide 49

Slide 49 text

WWW-Authentication Authorization: Token token=“7C1100AD4A6D45A6B2E022B”

Slide 50

Slide 50 text

No content

Slide 51

Slide 51 text

Public ~ vs ~ Private

Slide 52

Slide 52 text

OAuth ~ vs ~ Token

Slide 53

Slide 53 text

OAuth ~ vs ~ Token

Slide 54

Slide 54 text

Tokens Method URL Description POST /token Create new token
 (with login credentials) DELETE /token Delete token HEAD /token Check if token is active PATCH /token Renew a token (if tokens can expire)

Slide 55

Slide 55 text

1.Versioning 2.Headers 3.Error responses 4.Authentication! 5.REST Agenda

Slide 56

Slide 56 text

1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda

Slide 57

Slide 57 text

REST

Slide 58

Slide 58 text

Teams Method URL Description GET /my/teams Returns all teams POST /my/teams Create new team GET /my/teams/1 Return given team PATCH /my/teams/1 Update given team DELETE /my/teams/1 Delete given team

Slide 59

Slide 59 text

{
 “id”: 1, “name”: “Real Blagoevgrad”,
 “players”: { /* players */ } } POST /my/teams Accept: application/vnd.fantasy-football.com; version=1,application/json
 Authentication: Token token=“0BD8AF0AAB86619” X-Api-Key: “7C1100AD4A6D45A6B2E022B”

Slide 60

Slide 60 text

{
 “id”: 1, “name”: “Real Blagoevgrad”,
 “players”: { /* players */ } } GET /my/teams/1 Accept: application/vnd.fantasy-football.com; version=1,application/json
 Authentication: Token token=“0BD8AF0AAB86619” X-Api-Key: “7C1100AD4A6D45A6B2E022B”

Slide 61

Slide 61 text

{
 “id”: 1, “name”: “Bayern Blagoevgrad”,
 “players”: { /* players */ } } PATCH /my/teams/1 Accept: application/vnd.fantasy-football.com; version=1,application/json
 Authentication: Token token=“0BD8AF0AAB86619” X-Api-Key: “7C1100AD4A6D45A6B2E022B”

Slide 62

Slide 62 text

GET /teams Accept: application/vnd.fantasy-football.com; version=1,application/json
 Authentication: Token token=“0BD8AF0AAB86619” X-Api-Key: “7C1100AD4A6D45A6B2E022B” [{
 “id”: 1, “name”: “Bayern Blagoevgrad”,
 “owner”: { /* owner */ },
 “players”: { /* players */ }, }, { /* other team */ }]

Slide 63

Slide 63 text

Paging (1) X-Total: 10 X-Offset: 2 X-Offset: 3

Slide 64

Slide 64 text

Paging (2) Link: ; rel="next", ; rel=“previous”, ; rel=“first”, ; rel=“last”

Slide 65

Slide 65 text

Paging (3) Link: ; rel="next"

Slide 66

Slide 66 text

1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda

Slide 67

Slide 67 text

Bonus

Slide 68

Slide 68 text

Mobile API ~ vs ~ Regular API

Slide 69

Slide 69 text

Syncing / Offline

Slide 70

Slide 70 text

Postman Chrome plugin

Slide 71

Slide 71 text

Good API example http://developer.github.com/v3/

Slide 72

Slide 72 text

Questions?

Slide 73

Slide 73 text

@rstankov Thank you :)