REST (Representational State Transfer) is an architectural style, and an approach to communications that is often used in the development of Web services and nowadays with Mobile world and Internet of Things.

1. RESTFul Design
Principles
Geison Goes

2. REST (Representational State Transfer) is an architectural style,
and an approach to communications that is often used in the
development of Web services and nowadays with Mobile world
and Internet of Things.
What is REST
RESTFul Design Principles

3. The primary design principle when crafting your API
should be to maximize developer productivity and
success.
Main GOAL
RESTFul Design Principles

4. Nouns are good; verbs are bad!
Keep your base URL simple and intuitive, use HTTP Verbs:
Principle number 1 - CRUD Actions
RESTFul Design Principles
HTTP Verb Path - GOOD Path - BAD HTTP Status Response
GET /photos /getAllPhotos 200 JSON with a list of all photos
GET /photos/:id /getPhoto/:id 200 JSON with a photo
POST /photos /createPhoto 201 JSON with a new photo
PATCH/PUT /photos/:id /updatePhoto 200 JSON with updated photo
DELETE /photos /deleteAllPhotos 200 JSON with deleted photos
DELETE /photos/:id /deletePhoto 200 JSON with deleted photo

5. Just 2 entry points to perform all CRUD actions
Principle number 1 - CRUD Actions
RESTFul Design Principles
RESOURCE POST GET PUT DELETE
/photos Create a new photo Return all photos Update all photos Delete all photos
/photos/1234 405 Method not allowed Return photo Update photo or
return 400 not found
Delete photo or
return 400 not found

6. Keeps the CRUD actions just one level deep:
Principle number 2 - Associations
RESTFul Design Principles
RESOURCE POST GET PUT DELETE
/users/:id/photos Create a new photo for
this user
Return all photos
of this user
Update all photos of
this user
Delete all photos
/users/:id/photos/1234 405 Method not allowed Return this photo
of this user
Update this photo of
this user or return
400 not found
Delete this photo of
this user or return
400 not found

7. In order to facilitate the developers work, always provides
Eager and Lazy ways to get resources that have
associations.
Principle number 3 - Eager or Lazy Loading
RESTFul Design Principles

8. Lazy loading - get user photos:
Principle number 3 - Eager or Lazy Loading
RESTFul Design Principles
RESOURCE POST GET PUT DELETE
/users Create a new photo Return all photos Update all photos Delete all photos
/users/1234 405 Method not allowed Return photo Update photo or
return 400 not found
Delete photo or
return 400 not found
Step 1:
Step 2:
RESOURCE POST GET PUT DELETE
/users/1234/photos Create a new photo
for this user
Return all photos
of this user
Update all photos of
this user
Delete all photos
/users/1234/photos/1234 405 Method not
allowed
Return this photo
of this user
Update this photo of
this user or return
400 not found
Delete this photo of
this user or return
400 not found

9. Eager loading - get user photos:
Principle number 3 - Eager or Lazy Loading
RESTFul Design Principles
RESOURCE POST GET PUT DELETE
/users?include=photos 405 Method
not allowed
Return all Users
with his photos
Update all Users
and his photos
Delete all Users
and their photos
/users/:id/?include=photos 405 Method
not allowed
Return this User
with his photos
Update this User
with his photos
Delete this User
and his photos
/users?include=photos&comments 405 Method
not allowed
Return this User
with his photos and
comments
Update this User
with his photos
and comments
Delete this User
with his photos
and comments

10. Some times it is not necessary get all information about
resources, in fact is necessary just some fields or a specific
characteristic and also sorting and paginate the results.
Principle number 4 - Filters
RESTFul Design Principles

11. GET /users?fields=name,email,phone
GET /photos?fields=title,size,state
Principle number 4 - Filters
RESTFul Design Principles
Fields

12. GET /user?sort=age,name
fields with - sign will be sorting in descending order
GET /user?sort=age,-name
Principle number 4 - Filters
RESTFul Design Principles
Sorting

13. GET /photos?limit=25&offset=50
Principle number 4 - Filters
RESTFul Design Principles
Paginating

14. To have a complete REST API it was necessary implement
two kind of searches:
1. Global Search
GET /search?resources=photos&title=fog&size=small
GET /search?resources=photos,images&size=small
2. Scoped Search
GET /photos?title=fog&size=small
GET /users/1234/photos?title=fog&size=small
Principle number 5 - Search
RESTFul Design Principles

15. In order to provide to developers the necessary information
when erros happens, returns error messages in the
response body
HTTP Status Code: 401
{"code" : 401, "message": "Authentication Required"}
Principle number 6 - Error Handling
RESTFul Design Principles

16. Versioning the API is a way to keep backward compatibility,
to implement it, just provide the API version in the URI
GET /v1.0/users
Principle number 7 - Versioning
RESTFul Design Principles

17. Some times it is necessary to create APIs that are
responsible to perform actions instead of return resources,
these were the unique cases where verbs are allowed
GET /convert?from=EUR&to=CNY&amount=100
GET /calculate?operation=sum&val1=8&val2=4
Principle number 8 - Exceptions
RESTFul Design Principles

18. When resources could not be public, a authentication
mechanism becomes necessary and in this case there is
no question that the best approach to implement it is
OAuth2.
To get more information about OAuth2 and how to
implement it follow this links below:
- http://en.wikipedia.org/wiki/OAuth
- http://oauth.net/2/
Principle number 9 - Authentication
RESTFul Design Principles

19. Principle number 9 - Authentication
RESTFul Design Principles

20. RESTFul Design Principles
● Email:
○ geisonfgf@gmail.com
● Skype
○ geisonfgf
● Facebook
○ http://www.facebook.com/geisonfgf
● Twitter
○ http://www.twitter.com/geisonfgf
Contact me