The document describes EyeEm's transition from its second API version to a third, documentation-less version. The third API is designed to be intuitive, flexible, verbose, and discoverable through its use of RESTful principles and HATEOAS. It aims to optimize the developer experience and allow users to easily explore the API functionality through linked relationships between resources. An example is provided of how a user could search for another user, view their photos, like one, and then follow the first liker through linked URLs between the resources.

1. EyeEm
Ramzi Rizk
@ramz
Designing a documentation-less API
Rino Montiel
@rinoFM

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

4. API V2
• REST!
• Read Only!
• Anonymous and Authenticated access!
• JSON response
we eat our own dog food.

5. END OF LIFECYCLE

6. 6
https://api.eyeem.com/v2/photos/12345?
detailed=1&friends=1&totalFriends=10&like
s=1&totalLikers=20&albums=1&detailedAlb
ums=1&albumPhotos=1&commentType=det
ailed…..
Why rewrite?

7. 7
• Intuitive!
• Flexible!
• Verbose!
• Discoverable
Why rewrite?

8. API V3

9. 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. 10
• Optimized for native apps!
• Versioning (qualifier OR uri)!
• “fields” param allows granular control of response
content
users/{id}?fields=id,nickname,group(photos:10)
Flexible

11. 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. 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. 13
Find a user and follow the first
person to like their latest photo
Example

14. 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. 15
https://api.eyeem.com/v3/search
{
"search": {
"params": [
"type",
"query",
"fields"
]
},
"links": [
{
"rel": "self",
"href": "http://api.eyeem.com/api/v3/search"
}
]
}

16. 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. 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. 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. 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. 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. 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. 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. 23
Performance !
& !
Speed
Food for thought
Perfection !
&!
Specifications
VS

24. EyeEm
Ramzi Rizk
@ramz
ramz@eyeem.com
Rino Montiel
@rinoFM
rino@eyeem.com