The document discusses tips for crafting APIs according to REST principles. It outlines best practices like using nouns for resource identifiers, applying CRUD operations consistently via POST, GET, PUT, DELETE, and including hypermedia links to allow navigating through application states. Other topics covered include API versioning, error handling, and choosing an implementation technology based on performance needs like number of daily accesses. The document emphasizes designing APIs pragmatically with the goal of making them easy for application developers to use.

1. Crafting APIs
Thoughts and tips
Tatiana Al-Chueyr
@tati_alchueyr

2. We need to build an API for

3. UFC API
/getAllFighters
/playMatches
/createChallenge
/addFightToSchedule
/saveFight
/getPhotosOfRhonda
/listLast20News
/showMachida
/fights_by_jose_aldo

4. After all… UFC world is huge!

5. Keep the simple things simple.

6. UFC API
We only need base URLs as resources
/fighters
/fighters/JoseAldo
/events
/events/162

7. UFC API
What about actions?

8. UFC API
What about actions?
POST
GET
PUT
DELETE

9. UFC API
What about actions?
CREATE: POST
RETRIEVE: GET
UPDATE: PUT
DELETE: DELETE

10. UFC API
POST GET PUT DELETE
/figthers create a new
fighter
list fighters replace all fighters delete all fighters
/fighters/JoseAldo - show José Aldo update José Aldo
info
delete José Aldo

11. REST APIs
Don’t use verbs in resources identifiers
Use nouns

12. REST?
● Architectural style
● REpresentational State Transfer
● Response to the complexity of SOAP based
web services and many other standards
● Took off with Web 2.0
● Way to create easy to use web services

13. “A RESTifarian is a zealous proponent of
the REST software architectural style as
defined by Roy T. Fielding in Chapter 5 of
his PhD. dissertation at UCIrvine. You can
find RESTifarians in the wild on the
REST-discuss mailing list. But be careful,
RESTifarians can be extremely meticulous
when discussing the finer points of REST, as
I learned recently while participating on the
list. :)” by Mike Schinkel
http://mikeschinkel.com/blog/whatisarestafarian/

14. REST Principles
1. Client-server
2. Stateless server
3. Cache
4. Uniform interface
a. Identification of resources
b. Manipulation of resources through representations
c. Self-descriptive messages
d. Hypermedia as the engine of application state
5. Layered System
https://blog.apigee.com/detail/hateoas_101_introduction_to_a_rest_api_style_video_slides

15. REST Principles
Client-cache-stateless-server web
architecture…
which let us scale the web :)

17. REST Principles
1. Client-server
2. Stateless server
3. Cache
4. Uniform interface
a. Identification of resources
b. Manipulation of resources through representations
c. Self-descriptive messages
d. Hypermedia as the engine of application state
5. Layered System
https://blog.apigee.com/detail/hateoas_101_introduction_to_a_rest_api_style_video_slides

18. REST Principles
Layered system: let us add feature like a
gateway, load balancer and firewall

20. REST Principles
1. Client-server
2. Stateless server
3. Cache
4. Uniform interface
a. Identification of resources
b. Manipulation of resources through representations
c. Self-descriptive messages
d. Hypermedia as the engine of application state
5. Layered System
https://blog.apigee.com/detail/hateoas_101_introduction_to_a_rest_api_style_video_slides

21. REST Principles
4.a. Identification
http://urls.api.twitter.com/1/urls/count.json?url=http://g1.globo.com
4.b. Representation
{"count":39285,
"url":"http://g1.globo.com/"}
4.c. Messages and errors
http://urls.api.twitter.com/1/urls/counte.json?url=http://g1.globo.com
twttr.receiveCount({"errors":[{"code":48,"message":"Unable to access URL
counting services"}]})

22. REST Principles
4.d. Hypermedia as the engine of application
state (HATEOAS)
● In each response message include the links
for the next request message.
● And navigate your way through every state
of the entire application

24. HATEOAS
"The name 'Representational State Transfer' is intended to evoke an
image of how a well-designed Web application behaves: a network of
web pages (a virtual state-machine), where the user progresses
through the application by selecting links (state transitions), resulting in
the next page (representing the next state of the application) being
transferred to the user and rendered for their use."
Roy Fielding
Architectural styles and the Design of Network-based Software
Architectures, Chapter 6

25. HATEOAS
"If the engine of application state (and hence the API) is not being
driven by hypertext, then it cannot be RESTful and cannot be a REST
API. Period. Is there some broken manual somwhere that needs to be
fixed?"
Roy Fielding
"REST APIs must be hypertext-driven"
Untangled: Musings of Roy T. Fielding

26. HATEOAS in Practice
Install JSONBrowser plugin
And navigate:
http://brainiak.dev.semantica.globo.com/

27. HATEOAS +
● Good for browsing
● Good for indexing
● Good for generic applications (e.g. CMAaS)
● Kind of auto-documentation
● Can help when contracts change

28. HATEOAS -
● Too much work
● No established standard (JSON Schema is
progressing every day)
● Does it really help when contracts change?
● How pragmatic is it to use it?

29. RESTlike but not RESTfull
Is CloudStack API RESTfull?
"The short answer is that the CloudStack API is
RESTlike but not RESTfull since it is only
based on the GET method. Being an http
based API that can return JSON does not make
it a RESTfull API. This should not be seen as
negative criticism but just a clarification."
http://sebgoa.blogspot.com.br/2013/04/to-rest-or-not-to-rest.html

30. To REST or not to REST
Don't design any API to conform to REST just
for the REST's sake
Define which principles and practices are "best"
for a given application

31. RESTafarian or a Pragmatist

32. API Flamewars
Some discussions that showed off while we
were developing Brainiak API and some other
interesting points.
https://blog.apigee.com/detail/slides_for_restful_api_design_second_edition_w
ebinar/

33. Plurals x singulars
Foursquare
/checkins
GroupOn
/deals
Zappos
/Product

34. Plurals x singulars
Usually plurals are better….
But not always (e.g. Brainiak)
http://www.restapitutorial.com/lessons/restfulresourcenaming.html
http://stackoverflow.com/questions/6845772/rest-uri-convention-singular-or-plur
al-name-of-resource-while-creating-it

35. Abstract or concrete naming?
Super High
/things
High
/people
Medium
/fighters
Low
/brazilianFighers

36. Abstract or concrete naming?
Concrete is better than abstract:
/fighters

37. Errors
Facebook satus code: 200
{"type": "OAuthException", "message": "(#803) Some of the aliases you
requested do not exist: foo.bar"}
Twilio status code: 401
{"status": 401, "message": "Authenticate", "code":"20003", "more_info":
"http://www.twilio.com/docs/errors/20003"}
SimpleGeo status code: 401
{"code": 401, "message": "Authentication Required"}

38. Errors
Code for code
200 - OK
401 - Unauthorized
http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

39. Errors
Message for people
{"message": "verbose, plain language description of the
problem with hints about how to fix it",
"more_info": "http://link.to/more_info_about/errorx"}

40. Versioning
Twilio
/2010-04-01/Accounts/
salesforce.com
/services/data/v20.0/sobjects/Account
Facebook
?v=1.0

41. Versioning
This far, we used this for Semantic APIs at Globo.com:
/v1/fighters/

42. JSON attributes naming
Twitter
"created_at": "Thu Nov 03 05:19:38 +0000 2011"
Bing
"DateTime": "2011-10-29T09:35:00Z"
Foursquare
"createdAt": 13450391

43. JSON attributes naming
Use JavaScript Convention

44. Pagination
Facebook
offset
limit
Twitter
page
rpp
LinkedIn
start
count

45. Pagination
Globo.com
page
per_page

46. Idempotence
http://www.restapitutorial.com/lessons/idempot
ency.html

47. Other flamewars
What if the pagination has no results?
● Inexistent resource (404)
● Empty resource (200)

48. Other flamewars
How to provide optional parameters to a GET?
● Query string
● Payload

49. Other flamewars
In a pagination, should we return item_count
even if it slows down the performance in 50%?

50. Good REST API Example
Github
http://developer.github.com/v3/
https://api.github.com/orgs/globocom/repos
https://api.github.com/repos/globocom/tsuru/iss
ues?state=closed

51. Technology that fits your needs
What do you expect for…
● number of access per day..?
● number of updates..?
● number of reads..?
● need of database to store data..?

52. Technology that fits your needs
Depending on your needs, different python
libraries could help you:
● Django
● Flask
● Gevent
● Tornado

53. Asynchronous x Synchronous
"A simple approach to I/O would be to start the access and
then wait for it to complete. But such an approach (called
synchronous I/O or blocking I/O) would block the progress
of a program while the communication is in progress,
leaving system resources idle. When a program makes
many I/O operations, this means that the processor can
spend almost all of its time idle waiting for I/O operations to
complete."
http://en.wikipedia.org/wiki/Asynchronous_I/O

54. Who will access your API?
Will your API support cross origin access using
AJAX requests?
● CORS W3C working draft:
http://www.w3.org/TR/cors
● HTML 5 Security Guide:
http://code.google.com/p/html5security/wiki/
CrossOriginRequestSecurity

55. Final thoughts
● What problem are you solving?
● For whom is your API?
● What are the performance needs?
● Is an HTTP API the best solution? (e.g. have
a look at protocol buffers)
● Think about how to model your API before
implementing it

56. Final thoughts
Keep an eye on good reputation APIs
● Github
● ElasticSearch

57. Final thoughts
Be pragmatic.
For the benefit of application developers.
Keep your documentation up-to-date.

58. More tips on crafting APIs
http://www.restapitutorial.com/lessons/restquicktips.html
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#hateoas
http://mark-kirby.co.uk/2013/creating-a-true-rest-api/
http://www.slideshare.net/mario_cardinal/best-practices-for-designing-pragmati
c-restful-api
http://blog.luisrei.com/articles/rest.html

59. Thanks!
Tati Al-Chueyr
tatiana.martins@corp.globo.com
@tati_alchueyr