How to design RESTful API

1. by Mizan Rizqia
Designing a RESTful Web API

2. OUTLINE
●
Introduction
●
Quick Tips
●
Error Handling
●
Versioning
●
Paginate & Partial Respone
●
Timestamps
●
Authentication

3. Introduction
REST
Representational State Transfer
Software architecture style consisting of guidelines and best
practice for creating scalable web service

4. REST Architectural Constrains
● Client Server
● Stateless
● Cacheable
● Layered System
● Code on Demand
(optional)
● Uniform Interface
RESTful

5. 6 Quick Tips
1.Use HTTP Verbs to Mean Something
● GET
● POST
● PUT
● DELETE

6. 6 Quick Tips
2.Provide Sensible Resource Name
● Use identifier (clean URL)
● Good : /user/12345
● Poor : /api?type=user&id=23
● Design for your client, not for your data
● Resource name = NOUNS (avoid verb)
● Use PLURAL
● Use lower-case
● Keep URLs as SHORT as possible
Recommended :
/customers/33245/orders/8769/lineitems/1

7. 6 Quick Tips

8. 6 Quick Tips
3.Use HTTP Response Codes to Indicate
Status
Top 10 HTTP Status Code
● 403 FORBIDDEN
● 404 NOT FOUND
● 405 METHOD NOT ALLOW
● 409 CONFLICT
● 500 INTERNAL SERVER ERROR
● 200 OK
● 201 CREATED
● 204 NO CONTENT
● 400 BAD REQUEST
● 401 UNAUTORIZED

9. 6 Quick Tips
4.Offer Both JSON and XML
● Make the XML that is returned more JSON-like
● JSON-Schema (schema-style validation
capabilities)

10. 6 Quick Tips
5.Create Fine-Gained Resources
● Small resources
● Easy defined resources
● Provide CRUD functionality
● Use-case-oriented
6.Consider Connectedness
● RFC5988 : The HTTP Web Linking Spesification
● RFC3987 : International Resource Identifiers (IRIs)
● RFC4287 : Atom-Style links

11. Handling Errors
Why is good error design especially important
for API designer?
1. Developer learn to write code through error
2. Developer depend on well-designed error when they are
throubleshooting and resolving issues

12. Handling Errors Example
● Facebook
HTTP Status Code: 200
{"type" : "OauthException", "message":"(#803)
Some of the aliases you requested do not exist:
foo.bar"}

13. Handling Errors Example
● Twillio
HTTP Status Code: 401
{"status" : "401",
"message":"Authenticate","code": 20003,
"moreinfo":
"http://www.twilio.com/docs/errors/20003"}

14. Handling Errors Example
● SimpleGeo
HTTP Status Code: 401
{"code" : 401, "message": "Authentication
Required"}

15. Handling Errors
Use HTTP Status Code
Google
200 201 304 400 401 403 404 409 410 500
Netflix
200 201 304 400 401 403 404 412 500
Digg
200 400 401 403 404 410 500 503

16. Handling Errors
How many status codes should you use for your
API? (minimum)
1.Success – Everything worked
2.Client error – The application did something wrong
3.Server error – The API did something wrong
● 200 ­ OK
● 400 ­ Bad Request
● 500 ­ Internal Server Error
More info: HTTP Status Codes

17. Versioning
“Never Release an API without a version and
make the version mandatory”

18. Versioning Example
● Twilio
/2014­04­01/Accounts/
● Salesforce
/services/data/v20.0/sobjects/Accounts
● Facebook
?v=1.0

19. Versioning Recommendation
● Specify the version with a 'v' prefix, don't use the dot notation.
– /v1/dogs
– /v2/customers
● How many version should you maintain?
– At least one version back
● Should version and format be in URL or headers?
– If it logic, put in URL
– If it doesn't change logic (like Oauth), put it in the header

20. Pagination & Partial Respone
“Just give the information they need”

21. Pagination & Partial Respone
● LinkedIn
/people:(id,first­name,last­name,industry)
● Facebook
/joe.smith/friends?fields=id,name,picture
● Google
?fields=title,media:group(media:thumbnail)

22. Pagination & Partial Respone
● Recommendation
– Add optional fields in comma-delimited list
/dogs?field=name,color,location
/tickets?sort=­updated_at
/tickets?sort=­priority,created_at
– Use limit & offset to paginate object
/dogs?limit=25&offset=50

23. Search
● Global Search
/search?q=mizan+keren
● Scoped Search
/orders/1001?q=tlab+amazing
● Formatted Search
/search.xml?q=mizan+keren

24. Timestamp
● Don't use Unix Timestamps
– 1427736345 (ISO 8601:2015-03-30T17:25:45Z)
● Use standard Timestamps
– ISO-8601
– 2015-03-30T16:31:53+00:00
– 2015-03-30T16:31:53Z

25. Authentication
Three common ways to go with authentication
1. If your API has user-based authentication
Oauth2 - demo
2. If you just need to password protect
HTTP Basic Authentication (not secure)
3. if you want to provide an API key or other sorts of single-string
authentication
Oauth + HTTP Basic Authentication

26. Authentication – OAuth2 Flow

27. Complement with an SDK
● Speed adoption on a specific platform
● Simplify integration effort required to work with your
API
● An SDK can help reduce bad or inefficient code
● As a developer resource
– Yahoo
– Paypal
● To market your API specific community

28. Reference
● https://pages.apigee.com/web-api-design-ebook.html
● http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
● http://www.restapitutorial.com/
● http://bshaffer.github.io/oauth2-server-php-docs/
● http://code.tutsplus.com/tutorials/laravel-4-a-start-at-a-restful-api-updated--net-29785
● http://www.sitepoint.com/build-rest-resources-laravel/

29. Matur Sembah Nuwun
Thank you
Mizan Rizqia
baobaz@tlab.co.id
+62-81806406692
@mizanrizqia
/mizanr