Embed Size (px)
Citation preview
RESTFul Design Principles
Geison Goes
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
The primary design principle when crafting your API
should be to maximize developer productivity and
success.
Main GOAL
RESTFul Design Principles
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
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
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
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
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
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
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
GET /users?fields=name,email,phone
GET /photos?fields=title,size,state
Principle number 4 - Filters
RESTFul Design Principles
Fields
GET /user?sort=age,name
fields with - sign will be sorting in descending orderGET /user?sort=age,-name
Principle number 4 - Filters
RESTFul Design Principles
Sorting
GET /photos?limit=25&offset=50
Principle number 4 - Filters
RESTFul Design Principles
Paginating
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
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
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
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=100GET /calculate?operation=sum&val1=8&val2=4
Principle number 8 - Exceptions
RESTFul Design Principles
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
Principle number 9 - Authentication
RESTFul Design Principles
RESTFul Design Principles
● Email:
● Skype
○ geisonfgf
○ http://www.facebook.com/geisonfgf
○ http://www.twitter.com/geisonfgf
Contact me
