EyeEm

Ramzi Rizk @ramz

Designing a documentation-less API

Rino Montiel @rinoFM

EyeEm is the world’s premier community and marketplace for the photographer inside all of us

API V2

• REST!• Read Only!• Anonymous and Authenticated access!• JSON response

we eat our own dog food.

END OF LIFECYCLE

6

https://api.eyeem.com/v2/photos/12345?detailed=1&friends=1&totalFriends=10&likes=1&totalLikers=20&albums=1&detailedAlbums=1&albumPhotos=1&commentType=detailed…..

Why rewrite?

7

• Intuitive!• Flexible!• Verbose!• Discoverable

Why rewrite?

API V3

9

• RESTFUL: correct use of nouns / verbs!• standard pagination sequencing on

pagination response after={unique_id},limit=X!

!• consistent parameters

sort ={time || popular} type ={nearby || popular …} ll =52.2513,13.3425 order ={asc || desc} query ={string}

Intuitive

10

• Optimized for native apps!• Versioning (qualifier OR uri)!• “fields” param allows granular control of response

contentusers/{id}?fields=id,nickname,group(photos:10)

Flexible

11

• meta object in all responses!• http code in header and body!• custom error code w/ link in body!• custom message in body

Verbose

{ “meta”:{ “http_code”:200, “message”:“deprecated endpoint”, “error_code”:123, “error_url”:“https://www.github.com/eyeem/api/wiki/error_123” } “data”:{ … } }

12

• Self-documenting API!• Restful objects (1)!• automation, inline shema!

• HATEOAS (2)(3)!• really “surf” the api.

Discoverable

http://restfulobjects.org/!http://www.slideshare.net/josdirksen/rest-from-get-to-hateoas!http://en.wikipedia.org/wiki/HATEOAS

13

Find a user and follow the first person to like their latest photo

Example

14

https://api.eyeem.com/v3{ "links": [ { "rel": "search", "href": "http://api.eyeem.com/api/v3/search" }, { "rel": "users", "href": "http://api.eyeem.com/api/v3/users" }, … { "rel": "photos", "href": "http://api.eyeem.com/api/v3/photos" } ] }

15

https://api.eyeem.com/v3/search

{ "search": { "params": [ "type", "query", "fields" ] }, "links": [ { "rel": "self", "href": "http://api.eyeem.com/api/v3/search" } ] }

16

/search?type=user&q=ramz&fields=id,nickname

{ "search": { "result": [ { "id": "1013", "nickname": “ramz", "links": [ { "rel": "user", "href": "https://api.eyeem.com/api/v3/users/ramz" } ] } ] } }

17

{ "user": { "id": "1013", "nickname": "ramz", "fullname": "Ramzi Rizk", "links": [ { "rel": "self", "href": "http://api.eyeem.com/api/v3/users/1013" }, { "rel": "photos", "href": "http://api.eyeem.com/api/v3/users/1013/photos" } ] } }

/users/ramz

18

/users/ramz/photos?sort=time&order=desc{ "photos": { "limit": 1, "total": 2238, "items": [ { "id": "36373973", "updated": "2014-05-03T17:14:00+0200", "links": [ { "rel": "self", "href": "http://api.eyeem.com/api/v3/photos/36373973" } ] } ] } }

19

/photos/36373973{ "photo": { "id": "36373973", "updated": "2014-05-03T17:14:00+0200", "links": [ { "rel": "albums", "href": "http://api.eyeem.com/api/v3/photos/36373973/albums" }, { "rel": "likers", "href": "http://api.eyeem.com/api/v3/photos/36373973/likers" } ] } }

20

{ "likers": { "limit": 1, "total": 51, "items": [ { "id": "3097120", "nickname": “rinofm", "links": [ { "rel": "user", "href": "https://api.eyeem.com/api/v3/users/rinofm" } ] } ] } }

/photos/36373973/likers?sort=time&order=asc&limit=1

21

/users/rinofm{ "user": { "id": "3097120", "nickname": "rinofm", "links": [ { "rel": "self", "href": "http://api.eyeem.com/api/v3/users/3097120" }, { "rel": "followers", "href": “http://api.eyeem.com/api/v3/users/3097120/followers}“ }, ] } }}

22

{ "meta": { “http_code”:200, “message”:“ramz now follows rinofm” }, "data": { "followers": { "limit": 1, "total": 2986, "items": [ { "id": "1013", "nickname": “ramz" } ] } } }

PUT /users/rinofm/followers/me

23

Performance !& !

Speed

Food for thought

Perfection !&!

SpecificationsVS

EyeEm

Ramzi Rizk @ramz

ramz@eyeem.com

Rino Montiel @rinoFM

rino@eyeem.com