Joshua T Kalis he/him/his

I build great teams and excellent software.


Relax. You can do it.

The REST You Know

... is (probably) wrong.


But That's OK.

We're all in the same boat, so you're not alone.

Ready to get better?

[Audience participation]

I wont do that again.


What is REST and why do I care?


Here's what we are gonna cover.

What REST is not?

What is REST?

"The World Wide Web represents the largest implementation of a system conforming to the REST architectural style." ~ wikipedia

Architectural Constraints

  1. Client-Server
  2. Stateless
  3. Cache (cacheable)
  4. Uniform Interface + Resources + Representations + Messages + Hypermedia
  5. Layered System
  6. Code On-demand [optional]


Do these things and you are RESTful.

Missing any of them, however, means you are not.


Which is totally fine; just don't call it REST.

Resources + Representations

... will guide you towards REST

My personal belief.

Maturity Model

The Richardson Maturity Model describes the three steps towards the glory of REST.

RESTful enlightenment
(Level 3) Hypermedia Controls
(Level 2) HTTP Verbs & Status Codes
(Level 1) Resources
The swamp of POX - Plain 'ole XML

Some Basics - URLs



URL piece value
scheme http or [https, ftp, etc.]
port 80 (80 is default; assumed if nothing is provided)
path /path-to/resource
search ?filter=active
fragment #anchor - references an [id, name] in the page



RESTful HTTP APIs will be concerned with the path and search portions of the URI.

HTTP Verbs

Verb Action Idempotent Side-effects
POST Create no yes
GET Read yes no
PUT Update yes yes
DELETE Delete yes yes

* Left as an exercise for the brave and over-achieving.

Example Time

BAD Examples

  1. /v3/json/GetUser/1234 or /v3/GetUser/1234.json + Don't put the media type in the URI; put it in the request (accept) headers + Don't add verbs to the resource; use the proper HTTP verb + Pluralize the resource since it is a collection; 'Users' not 'User'
  2. /MyCollectionOfThings/789/InstanceOfObject/432/NameOfGrouping/Property + Don't filter properties in the URI; use a query to filter + Don't nest the URIs to match the data modeling; move resources closest to root as possible

The APIs that offer these endpoints are not RESTful.

You Want To Design A Good API?

You Want To Design A Good API.

Do These Things First

  1. Evaluate business process*
  2. Identify objects (Resources) that need be represented in the API
  3. Define Verbs for each Resource

* We are not going to cover this here.


A sample API plan for some pets.

/cats Create a new cat resource Retrieve a list of all Cats Update the list of all Cats Empty the list of all Cats
/cats/{id} error Retrieve Cat information Update info about a specific Cat Remove the Cat from the list of all Cats
/dogs Create a new dog resource Retrieve a list of all Dogs Update the list of all Dogs Empty the list of all Dogs
/dogs/{id} error Retrieve Dog information Update info about a specific Dog Remove the Dog from the list of all Dogs
/pets error Retrieve a list of all Pets error Empty the list of all Pets
/pets/{id} error Retrieve Pet information error Remove the Pet from the list of all Pets

Best Practices

Why Does Anyone Care?

Library (Helper) - AngularJS

  .service('API', function ($resource) {

    return {
        Dogs: $resoure('/dogs')

  .controller('MainCtrl', function (API) {
      .get(function (data) {
        // Do something with data

        // New Dog representation saved to collection

Library - Fermata

var api = fermata.json(''),
    Dogs = api.dogs;

Dogs.get(function (err, data) {
  // data is a JavaScript object
});{/* data */}, function (err, result) {
  // report success or failure

Good Reasons

Better Reasons

All of the above are achievable with REST if employed correctly and consistently.

And the best reason...

Look like a genius

Thank You

Joshua T Kalis