RESTful Web APIs

What's the intent of this presentation?

To get you to build RESTful web APIs, and to use the hypermedia constraint as a tool for doing that.

How do you get someone to use something?

force

1. inspire them to want to use it
2. show them how to use it

Why build RESTful Web APIs?

Constraints restrict complexity.

Flexibility for growth.

Ubiquitous support.

REST has 4 constraints

• identification of resources
• manipulation of resources through representations
• self-descriptive messages
• hypermedia as the engine of application state

Is REST new?

*muttering* Just seems like hype to me!

No.

REST (Representational State Transfer) is merely an academic codification of the architectural constraints that describe the Web.

Working RESTfully means leveraging the Web as a core technology and organizing principle.

How do we generally approach writing programs?

We model what we think needs to happen.

We check for libraries that support our use case.

We re-model our first pass given existing libraries.

We write our program in the context of a dependency graph.

If we approach the "Web" as libraries we can use, what do we get out of the box?

Protocol semantics.

Domain semantics.

Application semantics.

What are protocol semantics anyway?

"the set of rules regarding how to fashion valid requests and responses using one or more message protocols"

Yeah, yeah yeah... I've seen POST, PUT, DELETE, etc...

HTTP alone has a lot more semantics than you might think.

• RFC 7230, HTTP/1.1: Message Syntax and Routing
• RFC 7231, HTTP/1.1: Semantics and Content
• RFC 7232, HTTP/1.1: Conditional Requests
• RFC 7233, HTTP/1.1: Range Requests
• RFC 7234, HTTP/1.1: Caching
• RFC 7235, HTTP/1.1: Authentication

HTTP/2 was published as RFC 7540 in May 2015.

Meh. Why not just overload POST with everything you need?

When you use POST with overloaded semantics, you're limiting yourself to thinking in function calls.

Your alternative is message passing. Does the Web offer that?

Yes.

One of the Fielding constraints of REST is "self-describing messages", because the web requires a message passing style for its distributed model.

What can message passing give us that function calling can't?

Formally, they're equivalent. But if you expose functions, you've exposed method signatures, which couple your client's implementation to yours directly.

Instead we want to think declaratively: send a message of the desired state change, don't ask for a specific function to handle it.

The key in making great and growable systems is much more to design how its modules communicate rather than what their internal properties and behaviors should be. Think of the internet - to live, it (a) has to allow many different kinds of ideas and realizations that are beyond any single standard and (b) to allow varying degrees of safe interoperability between these ideas.

If you focus on just messaging - and realize that a good metasystem can late bind the various 2nd level architectures used in objects - then much of the language-, UI-, and OS based discussions on this thread are really quite moot.

Alan Kay (inventor of Smalltalk), on messaging

For instance, if you want to create something and format your POST request wrong, the server could inspect your malformed message and reply with a response explaining how to actually create the new resource you were addressing.

If you're POST'ing essentially to just an undefined function (RPC-style) the server can't do any better than say "this doesn't exist in my namespace. :c"

Our standard error response:

{
  key: "system_error"
  message: "An unexpected error has occurred. Please contact support if the problem persists."
}

Collection+JSON write template:

"template" : {
  "data" : [
     {"name" : "full-name", "prompt" : "Full Name"},
     {"name" : "email", "prompt" : "Email"},
     {"name" : "blog", "prompt" : "Blog"},
     {"name" : "avatar", "prompt" : "Avatar"}
   ]
}

Protocol semantics help define the control flow of our application, but they would be a pretty weak application on their own.

If we need more than CRUD, we need our own application semantics. So protocol semantics at bottom, application semantics at top...

Between "the HTTP request necessary to trigger a state transition" and "the purpose of the state transition"...

How do we fill the gap?

Hypermedia

"a way for the server to tell the client what HTTP requests the client might want to make in the future"

H-Factors are the categories of state transitions that hypermedia can help the client and server format as representations (messages).

Search


  Search term:
  
  



  Keywords:
  
  

So how do we design a RESTful API? (In brief.)

1. Semantic descriptors: list all info a client might have as input/output

2. Link relations: Draw a state diagram

3. Check against existing profiles: can you leverage any?

4. Choose a media type

5. Write your profile of your application semantics

   The more you found in 3 and 4, the less you need to do in 5.

6. Code!!

7. Publish the "billboard URL"

ZipErrands API

Use case: As a Zipcar member, I want to find the nearest car available, so that I can use it to run an errand that will take under an hour.

Input: current location of user.

Output: cars (must have distance to, features, picture of), car keys (allows device to unlock car), reservation invoice (billed amount).

Semantic descriptors: current_location, distance_to, features, picture_of, car_keys, reservation_invoice

Link relations: search, car, prev/next, back, claim

Reconcile names:

• current_location, distance_to: GeoCoordinates
• reservation_invoice: Invoice
• claim: RentalCarReservation
• car: Car
• cars: SearchResultsPage

Why reconcile names?

Search engines like Google have a vested interest in being able to parse content on the web semantically. Ever received an email that highlighted your upcoming flight?

That's the power of using Schema.org markup.

What do we need out of a media type?

A way for the client to figure out: what kind of requests can I make, how do I make them, and why would I want to make them?

worst case: Protocol Semantics

best case: Application Semantics

[
  {
    "account_billing_info_id": 5639575,
    "account_id": 123456789,
    "last_four": "1111",
    "credit_card_type": "vi",
    "account_holder_name": "Suzanne Job",
    "primary": true,
    "expiration_month": "02",
    "expiration_year": "2019",
    "address_line_one": "35 Thomson place,",
    "address_line_two": "Apt No-105",
    "mumciplaity": "boston",
    "region": "Massachusetts",
    "country": "US"
  }
]

The media type most devs are familiar with is JSON, but it is not a hypermedia format.

What could a hypermedia format give us out of the box that a vanilla data structure like JSON can't?

As a client, how do I interpret x?

As a client, how do I make a request to find x?

"queries" : [
  {
    "rel" : "search", "href" : "http://example.org/friends/search",
    "prompt" : "Search",
    "data" : [
          {"name" : "search", "value" : ""}
    ]
  }
],

  Search term:
  
  

As a client, how do I make a request to find ys related to x?

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON API paints my bikeshed!",
      "body": "The shortest article. Ever."
    },
    "relationships": {
      "author": {
        "data": {"id": 42, "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": 42,
      "attributes": {
        "name": "John"
      }
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/atom+xml

When we give a uniform (standardized) interface to the client, we don't need as many clients.

Obligatory RentalCarReservation example.