RESTful Web APIs

How do you get someone to use something?

force

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

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.

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

Protocol semantics.

Domain semantics.

Application semantics.

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"}
   ]
}

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

How do we fill the gap?

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

<img src="http://www.example.org/images/logo" title="company logo">

<a href="http://www.example.org/search" title="view search page">Search</a>

<form method="get">
  <label>Search term:</label>
  <input name="query" type="text" value="">
  <input type="submit">
</form>

<form method="post" action="http://www.example.org/my-keywords">
  <label>Keywords:</label>
  <input name="keywords" type="text" value="">
  <input type="submit">
</form>

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.

[
  {
    "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?

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Person",
  "address": {
    "@type": "PostalAddress",
    "addressLocality": "Seattle",
    "addressRegion": "WA",
    "postalCode": "98052",
    "streetAddress": "20341 Whitworth Institute 405 N. Whitworth"
  },
  "colleague": [
    "http://www.xyz.edu/students/alicejones.html",
    "http://www.xyz.edu/students/bobsmith.html"
  ],
  "email": "mailto:jane-doe@xyz.edu",
  "image": "janedoe.jpg",
  "jobTitle": "Professor",
  "name": "Jane Doe",
  "telephone": "(425) 123-4567",
  "url": "http://www.janedoe.com"
}
</script>

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" : ""}
    ]
  }
],

<form method="get">
  <label>Search term:</label>
  <input name="query" type="text" value="">
  <input type="submit">
</form>

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
<link href="http://www.example.org/data/q1w2e3r4" rel="related" hreflang="en">

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