Is a presentation on how to design your next API following standards out there and best practices.

1. Building an API the right way
@kurenn

2. How does a web-service works?

3. ServerClient
Request
Response
Request
Response
Request
Response
Each request
generates a response,
could be a success or
and error response.
This is how the REST
API currently works.
REST is about
exposed resources so
we can perform
operations on things
and get back
responses
Client-Server Communication

4. Resources

5. Individual Resource Representation
An individual resource should be represented as a simple
JSON object
{
"user": {
"id": 1,
"email": "kurenn@icalialabs.com",
"name": "Abraham Kuri"
}
}

6. Multiple Resource Representation
A collection of resources should be represented as an
array of JSON objects
{
"users": [{
"id": 1,
"email": "kurenn@icalialabs.com",
"name": "Abraham Kuri"
}, {
"id": 2,
"email": "edolopez@icalialabs.com",
"name": "Eduardo Lopez"
}]
}

7. To-One Relationship Resource Representation
An object embedded into another one
{
"post": {
"id": 1,
"content": "This is my giving a SG talk",
"created_at": "2014-10-12T19:34:23Z",
"author": {
"id": 1,
"name": "Abraham Kuri"
}
}
}

8. To-Many Relationship Resource Representation
An object embedded with a collection
of other related objects
{
"book": {
"id": 1,
"title": "API's on Rails",
"authors": [{
"id": 1,
"name": "Abraham Kuri"
}, {
"id": 2,
"name": "Osvaldo Ayala"
}]
}
}
Be aware that this
may be inefficient,
due to the number of
authors.
In this case creating
another endpoint for
authors, would be a
good solution.

9. GET
Use it to fetch a resource or collection of resources
/books
/books/1
200 - Success
/books/1/authors

10. POST
Use to create a single resource, but some API’s may support
multiple creation
/books
201 - Created
/books/1/authors

11. PUT
Use to update a resource, but some API’s may support
multiple resource update
/books/1
200 - Success
/authors/1

12. DELETE
Use to delete a specific resource
/books/1
204 - No Content
/authors/1

13. Meta
"meta": {
"pagination": {
"per_page": 20,
"total_pages": 1,
"total_objects": 2
}
}

14. Content Negotiation

15. Server
Client
Request
JSON
Request
XML
Request
HTML
The API should be
able to process
multiple types of
content to send to the
client.
Understanding Content-Negotiation
Client
Client
This can be easily
achieve by appending
the format to the URI
http://api.icalialabs.com/members.json

16. Using the Accept Header for Content Negotiation
Accept: “application/json”
http://api.icalialabs.com/members

17. I18n

18. Using the Accept-Language Header
for Internationalization
Accept-Language: “es”
http://api.icalialabs.com/members
This way the API supports multiple languages for the response

19. Versioning
Versioning helps prevent major changes from breaking existing clients

20. Versioning
Through the URL
http://api.icalialabs.com/v1/members
Through an Accept Header
http://api.icalialabs.com/members
Accept: application/vnd.icalialabs.com+json; version=1

21. Authentication
Authentication is how servers prevent unauthorized access to protected resources.

22. Authentication
There are two ways you can authenticate clients
Basic Authentication
Token Based Authentication
GET /episodes HTTP/1.1
Host: localhost:3000
Authorization: Token token=16d7d6089b8fe0c5e19bfe10bb156832
GET /episodes HTTP/1.1
Host: localhost:3000
Authorization: Basic Zm9vOnNlY3JldA==

23. Understanding denied access
You should handle the unauthorized access with a WWW-
Authenticate header with a 401 HTTP code response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Application"
Content-Type: text/html; charset=utf-8
“realm” is used for different protection spaces, in this case is the whole
application

24. http://jsonapi.org/
http://apionrails.icalialabs.com/book/
https://github.com/rails-api/active_model_serializers
http://jsonapi.org/extending/
Where to go next?
http://sudo.icalialabs.com/a-short-story-on-timming-attack/

25. Thanks!