how restful is your rest?

How Restful is Your Rest?Abdelmonaim Remani

@PolymathicCoder

Øredev 2012Malmö, Sweden

Creative Commons Attribution Non-Commercial 3.0 Unported http://creativecommons.org/licenses/by-nc/3.0

Disclaimer: The graphics, logos, and trademarks used this presentation belong to their rightful owners.

License

Trevligt att träffa dig nordisk hackare!

Software Architect at Just.me Inc. Interested in technology evangelism and enterprise

software development and architecture Frequent speaker (JavaOne, JAX, OSCON, OREDEV,

etc…) Open-source advocate President and founder of a number of user groups

NorCal Java User Group The Silicon Valley Spring User Group The Silicon Valley Dart Meetup

Bio: http://about.me/PolymathicCoder Twitter: @PolymathicCoder Email: abdelmonaim.remani@gmail.com

About Me

Let’s Get Started!

Application Programming Interface You have an API when

(All or a part of) the functionality of your system is exposed In the form a well-defined interface (or a collection of interfaces)

of services That are externally accessible And programmatically consumable through to a well-defined protocol

You have a Web API when The functionality of your system is exposed In the form of a collection of Web Services

That are publicly addressable through a set of Web endpoints (URLs) And programmatically consumable though HTTP protocol

What is an API?

Web 2.0 Convenience and standardization around accessing

data and services Explosion of Open APIs

Location-Based (Maps, Geo-coding, Weather, Traffic, Etc…)

Financial Data Social Data Government Data, NGOs, etc… Etc…

Why Bother?

The birth of Mashups (Hybrid Web Applications) Combines services to create a value-added Aggregate and visualize data in interesting ways

Spoiled user-base that demands a lot more than what a single service can offer I want to see the closest Moroccan restaurants to

my current location on a map along with consumer ratings and whether any of my friends has recently checked-in in the last 30 days

Why Bother?

Mobile A lot more apps than browsers Mobile traffic is diminishing web traffic

exponentially Mashups 2.0 is Mobile

Why Bother?

You goal behind exposing a Web API should be for your services to be mashed up with others Beneficial

Will drive traffic in your direction Will allow you to learn about your own services and how

they are being used Will create goodwill with new potential users

Implies The majority of the traffic is NOT going to be through

your own app or website Your App is the API it exposes

Why Bother?

You have very little control on how your API will be used You do not control how your services are

orchestrated (Used in combination) Public APIs are forever

Better get it right the first time!

Challenges

How does a good API feel like? Easy to learn and use

Intuitive POLA (Principle of Least Astonishment)

Consistent Based on standards Adheres to a convention

Hard to misuse Well-Documented

What’s Right?

What is REST?

REpresentational State Transfer Roy Fielding Dissertation (Chapter 5-6)

Architectural Styles and the Design of Network-based Software Architectures

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

What is REST?

Goals Scalability Generality of Interface Independent Deployment of Component Intermediary Components

Rest Constraints Client-Server Stateless Conversion Cacheable Uniform Interface Layered System Code on-demand (Optional)

What is REST about?

Leveraging the web as a platform Resource-Oriented

Anything exposed on the web is a resource (Documents, video, device, etc…)

Resources are identifiable and addressable by URIs

An architecture based on the HTTP protocol

What is REST about?

API Design

Leonard Richardson http://www.crummy.com/writing/speaking/2008

-Qcon/

Richardson Maturity Model

The Address Book

A Simple address book that allows users to manage their contact data A user has a username and is associated with a set of contacts A contact is constitute of: a unique ID, a name, and a phone number User Stories:

As a user, I want to add a contact to my address book As a user, I want to list all contacts in my address book As a user, I want to view a specific contact in my address book As a user, I want to modify a specific contact in my address book As a user, I want to delete a specific contact from my address book As a user, I want to email a specific contact in my address book to a friend

The Address Book

Single URI Identify all possible operations/functionality indicate the desired operation in the payload

Single HTTP Verb

Richardson Maturity ModelLevel 0

SOAP-Based RPC Web Service Endpoint

http://www.polymathiccoder.com:9999/ws/addressbook WSDL

http://www. polymathiccoder.com:9999/ws/addressbook?wsdl addContact(“bob”, “Abdel Remani”, “(123) 123-1234”) lookupAllContacts(“bob”) lookupContactById(“bob”, 123) editContact(“bob”, 123, “Abdelmonaim Remani”, “(123) 123-

1234”) deleteContact(“bob”, 123) emailContact(“bob”, 123, “sandy@polymathiccoder.com”) markAsFavorite(“bob”, 123)

The Address Book at Level 0

Multiple URLs One URL per method URI encoded operations

Single Verb GET is used to change stage GET should be safe or idempotent

Richardson Maturity ModelLevel 1

URL Tunneling Endpoints

http://www. polymathiccoder.com/addressbook/add-contact?user=bob&name=Abdel%20Remani&phone-number=(123)%20123-1234

http://www. polymathiccoder.com/addressbook/lookup-all-contacts?user=bob

http://www. polymathiccoder.com/addressbook/lookup-contact?user=bob&id=123

http://www. polymathiccoder.com/addressbook/edit-contact?user=bob&id=123&name=Abdelmonaim%20Remani&phone-number=(123)%20123-1234

http://www. polymathiccoder.com/addressbook/delete-contact?user=bob&id=123

http://www. polymathiccoder.com/addressbook/email?user=bob&id=123&to=sandy@polymathiccoder.com

http://www. polymathiccoder.com/addressbook/mark-as-favorite?user=bob&id=123

The Address Book at Level 1

Level 2 Many URI Leverage multiple HTTP Verbs

You might call yourself Restful at this point Creating a uniform interface based on the

HTTP protocol

Richardson Maturity ModelLevel 2

The Address Book at Level 2

The Restful Address Book

Find all the nouns in users stories

Recourse Identification

Here are all the nouns we found: User

Uniquely identifiable by a username Contact

Uniquely identifiable by an id Let’s start calling nouns resources

Recourse Identification

Resources are identifiable and addressable by URIs The collection of resources the same kind

Users /users

Contacts /contacts

The individual resources within its collections The User whose username is “abdel”

/users/abdel The Contact whose ID is “123”

/contacts/123

Recourse Identification

Is there association between any of our resources? User has many Contacts A User can is the parent resource of a Contact

Chaining resources together “/” in a URI implies hierarchy Contact whose id is “123” and owner is the

User whose username is “abdel” /users/abdel/contacts/123

Recourse Identification

We end with 2 URIs referring to the same Contact resource whose ID is “123” /contcats/123 /users/abdel/contacts/123

We ask the question: Can a “Contact” recourse exist independently from “User” resource? The Answer is NO in this case /contcats/123 /users/abdel/contacts/123

Recourse Identification

User Stories:

Leveraging HTTP Verbs

CRUD Operations map to HTTP Verbs GET for Read POST for Create PUT for Update DELETE for Delete

Leveraging HTTP Verbs

To view all Abdel’s contacts GET /users/abdel/contacts

To view Abdel’s contact whose ID is 123 GET /users/abdel/contacts/123

To add a new contact to Abdel’s address book POST /users/abdel/contacts

To update Abdel’s contact whose is ID is 123 PUT /users/abdel/contacts/123

To delete Abdel’s contact whose is ID is 123 DELETE /users/abdel/contacts/123

Leveraging HTTP Verbs

Non-CRUD operations do not map to HTTP verbs Use descriptive verbs in URLs as Controller calls

To email Abdel’s contact whose ID is 123 to sandy@polymathiccoder.com GET /users/abdel/contacts/123/email?

to=sandy@polymathiccoder.com To mark Abdel’s contact whose ID is 123 to

sandy@polymathiccoder.com PUT /users/abdel/contacts/123/mark-as-favorite

Non-CRUD

Convention for your URLs RFC 3986: URLs are case sensitive

No CAPS to avoid confusion No camel-case

Links are usually underlined Use Hyphens instead of Underscores for

readability

The Opinion Shop: URLs

For a resource identified by the same URI Representation in the form of MIME/Media

Types Multiple data representation is supported

Use “Accept” HTTP Header Avoid file extensions

Manipulation is supported through multiple data representation Use “Content-Type” HTTP Header

Resource Representation

Convention object names in payload No JavaScript Convention

http://javascript.crockford.com/code.html No camel-case

I prefer using using Hyphens to be consistent with URLs

The Opinion Shop: URLs

1xx: Informational 2xx: Success 3xx: Redirection 4xx: Client Error 5xx: Server Error

Leveraging HTTP Status Codes

200 – OK Success Error with details in the body

201 – Created 202 – Accepted 400 – Bad Request 401 – Unauthorized 403 – Forbidden 404 – Not Found 405 – Method Not Allowed 406 – Not Acceptable 409 – Conflict 412 – Precondition Failed 415 – Unsupported Media Type 500 – Server Problems

Leveraging HTTP Status Codes

HATEOAS Hypermedia As The Engine Of Application Sate

Business Workflow Capturing the different states of a resource Transitions Endpoint

Returning all possible links given the current state of the resource

Richardson Maturity ModelLevel 4

Partials and Variations

Use Query Parameters Pagination

Don’t do this /page/1

Inspired by SQL ?limit=20&offset=20

Inspired by RFC 5005: Feed Paging and Archiving http://tools.ietf.org/html/rfc5005 ?next=20&to-item=6783&inclusive=true ?prev=23&to-item=6783&inclusive=false

Pagination

Use Query Parameters Ordering and Sorting

?order-by=populatrity&sorted-as=desc ?order-by=first-name&sorted-as=asc

Filtering ?filter-by= Etc…

Ordering, Sorting and Fitering

Support custom views of the data at the schema level Use an easy expression language

?fields=(first-name,phone-number) ?fields=!(last-name)

Google, LinkedIn, and others use a variations Support different predefined views of the data

Use ?view=brief ?view=full

Views

Legacy Clients

Older Clients Only support GET and POST HTTP Methods

Use ?method=put

Legacy Clients

Security

Remember that your Web Services must be stateless Do not use cookies or HTTP session under any

circumstances The client must send credentials to autenticate with

very call Options

HTTP Security Preemptively Setting “Authorization” HTTP Header Basic or Digest

OAuth

Security

Testing You API

Spring RestTemplate http://static.springsource.org/spring/docs/3.1.x/

spring-framework-reference/html/remoting.html#rest-resttemplate

Jayway’s Rest-Assured http://code.google.com/p/rest-assured/

Testing

Versioning

Don’t do this /api/v1/… ?v=1 /api/v1.1/… /api/07-19-2012/…

Use HTTP Headers Use Vendor-Specific MIME/Media Types Accept

application/vnd.polymathiccoder.addressbook+json

Versioning

Documentation

What to document Endpoint Description Prerequisites Request Response

Documentation

What to document Use a mind map

Documentation

Refer to other’s documentations Twitter, Facebook, Google, etc…

ioDocs from Mashery http://www.mashery.com/product/io-docs Live Example:

http://developer.rottentomatoes.com/iodocs

Documentation

How Restful Is REST?

Richardson Maturity Model as a reference It’ll tell where you stand

How Restful do you want to be? Dogmatic vs. Pragmatic In Common Law, there is this concept of “The

Reasonable Man” Being reasonable is relative Look in similar situation Similar expertise Custom and usage

How Restful Is Your REST?

Question?

Recommended Reading

Tack själv!

PolymathicCoder