REST API Dos and Dont's: Best Practices for Designing RESTful APIs

REST API
Dos and
Dont`s
@abonfiglio
Adriano Bonfiglio

What is REST and RESTful APIs
HTTP Methods
HTTP Status Code
Resources and Endpoints
Relations
Pagination
DEMO
Authentication
Agenda

SAP Labs Latin America
Adriano Bonfiglio

300,000
customers in
190 countries
More than
76,500
employees and offices in
130 countries
More than
€ 20,8
billion
in 2015
Annual revenue of
A 44-year history of innovation and
growth as a true industry leader

The best company to work
for in Brazil
Named by Você S/A magazine and
Great Place to Work
2015
2015
2015

Multi-cultural environment
Training (+24 hours/year/employee)
Competitive compensation policy
Flexible working time
Flexible benefits
SAP Bus
Free drinks & snacks
Benefits

Bachelor degree
in progress or complete
IT Technical knowledge
Business process knowledge
Advanced English skills
Spanish skills (plus)
Passion for innovation
Team player
How to work @ SAP

http://bit.ly/1Qs0Z7a
Join our talent community!
And get to know about our opportunities

REST
REpresentational
State
Transfer

REST API v1
router.get("/app/users/findAll", userController.list);
response: {message: ok, results:[...]}
router.get("/app/user/findOne/:id", userController.findOne);
response: {message: ok, results:{}}
router.post("/app/user/update/:id", userController.update);
router.post("/app/user/save", userController.save);
router.get("/app/user/delete/:id", userController.remove);
response: {message: ok}

router.post("/app/user/update/:id", userController.update);
router.get("/app/user/delete/:id", userController.remove);
FIRST PROBLEM
REST API v1

HTTP Methods
GET
POST
get a representation of a resource
create a new resource
PUT update a resource
PATCH update part of a resource
DELETE delete a resource

router.put("/app/user/update/:id", userController.update);
router.delete("/app/user/delete/:id", userController.remove);
REST API v2

SECOND PROBLEM
REST API v2

HTTP Status
2xx Success
3xx Redirection
200: Ok
201: Created
204: No content
304: Not modified
4xx Client Error 404: Not Found,
400: Bad Request,
401: Unauthorized,
403: Forbidden,
405: Method not allowed,
422: Unprocessable Entity

response: HTTP1.1 200 OK {message: “”, results:[...]}
response: HTTP1.1 200 OK {message: ok, results:{}}
response: HTTP1.1 200 OK {message: “”, results:{}}
response: HTTP1.1 201 Created {message: “”, results:{}}
response: HTTP1.1 204 No Content
REST API v3

response: HTTP1.1 200 OK {message: ok, results:{}}
REST API v3
THIRD PROBLEM

Resources and Enpoints
Nouns
Plural
Consistent

router.get("/app/users/", userController.list);
router.get("/app/users/:id", userController.findOne);
response: HTTP1.1 200 OK {message:””, results:{}}
router.put("/app/users/:id", userController.update);
router.post("/app/users/", userController.save);
router.delete("/app/users/:id", userController.remove);
REST API v4

What about Relations?
User
Role

router.get("/app/users/:id/roles", userController.findAll);
router.get("/app/users/:id/roles/:roleId", userController.findOne);
router.put("/app/users/:id/roles/:roleId", userController.update);
router.post("/app/users/:id/roles", userController.save);
router.delete("/app/users/:id/roles/:id", userController.remove);
What about Relations?

GET /app/users?page=1&order=desc&sort=name
What about Pagination?

GET /app/users?fields=name,lastname
Fields

Keep it Simple
GET http://got/hodor
Respose:
HTTP1.1 200 OK
{
“message”:”hodor”
}

GET http://localhost://users/1
Respose:
HTTP1.1 200 OK
{
“c_id”:”1”,
“c_interna_id”:”12132”,
“c_Name”:”foo”,
“c_lastName”:”barr”,
“c_structure”: {
“reference”:”32434”,
“code”:”2454435”,
},
“c: last_modified”: “02-29-2016”
}
Keep it clear & clean

GET http://localhost://users/1
Respose:
HTTP1.1 200 OK
{
“id”:”1”,
“name”:”foo”,
“lastName”:”barr”,
“last_modified”: “02-29-2016”
}
Keep it clear & clean

Authentication
GET / HTTP/1.1
Host: example.org
Authorization: Basic Zm9vOmJhcg=
BASIC

References
RESTful Web APIs – O`REILLY
https://developer.github.com/v3/
https://developers.trello.com/advanced-reference
https://github.com/adrianobonfiglio/rest-api

REST API Dos and Dont's: Best Practices for Designing RESTful APIs

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (8)

Similar to REST API Dos and Dont's: Best Practices for Designing RESTful APIs

Similar to REST API Dos and Dont's: Best Practices for Designing RESTful APIs (20)

Recently uploaded

Recently uploaded (20)

REST API Dos and Dont's: Best Practices for Designing RESTful APIs