restful api design

by Mizan Rizqia

Designing a RESTful Web API

OUTLINE

● Introduction

● Quick Tips

● Error Handling

● Versioning

● Paginate & Partial Respone

● Timestamps

● Authentication

Introduction

RESTRepresentational State Transfer

Software architecture style consisting of guidelines and best practice for creating scalable web service

REST Architectural Constrains

● Client Server● Stateless● Cacheable● Layered System● Code on Demand

(optional)● Uniform Interface

RESTful

6 Quick Tips

1.Use HTTP Verbs to Mean Something● GET● POST● PUT● DELETE

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

6 Quick Tips

6 Quick Tips

3.Use HTTP Response Codes to Indicate StatusTop 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

6 Quick Tips

4.Offer Both JSON and XML● Make the XML that is returned more JSON-like● JSON-Schema (schema-style validation

capabilities)

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

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

Handling Errors Example

● Facebook

HTTP Status Code: 200

{"type" : "OauthException", "message":"(#803) Some of the aliases you requested do not exist: foo.bar"}

Handling Errors Example

● Twillio

HTTP Status Code: 401

{"status" : "401", "message":"Authenticate","code": 20003, "moreinfo": "http://www.twilio.com/docs/errors/20003"}

Handling Errors Example

● SimpleGeo

HTTP Status Code: 401

{"code" : 401, "message": "Authentication Required"}

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

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

Versioning

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

Versioning Example

● Twilio/2014­04­01/Accounts/

● Salesforce/services/data/v20.0/sobjects/Accounts

● Facebook?v=1.0

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

Pagination & Partial Respone

“Just give the information they need”

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)

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

Search

● Global Search/search?q=mizan+keren

● Scoped Search/orders/1001?q=tlab+amazing

● Formatted Search/search.xml?q=mizan+keren

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

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

Authentication – OAuth2 Flow

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

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/

Matur Sembah NuwunThank you

Mizan Rizqia

baobaz@tlab.co.id

+62-81806406692

@mizanrizqia

/mizanr