5-5-2014 - api days - documentationless api
24
EyeEm Ramzi Rizk @ramz Designing a documentation-less API Rino Montiel @rinoFM
-
Upload
eyeem -
Category
Technology
-
view
151 -
download
1
Transcript of 5-5-2014 - api days - documentationless api
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
Rino Montiel @rinoFM
