RESTful Web APIs
By Leonard Richardson, Mike Amundsen; Sam Ruby
notes
highlights
a fiat standard,
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
The web server isn’t sitting up late at night worrying about Alice.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
RFC 1738
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
In REST terms, putting information about URL construction in separate human-readable documents violates the principles of connectedness and self-descriptive messages.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
application/vnd.collection+json, you’ll discover that it’s a media type registered for Collection+JSON.[7]
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Collection+JSON is a standard for publishing a searchable list of resources over the Web. JSON puts constraints on plain text, and Collection+JSON puts constraints on JSON.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Collection+JSON is a way of serving lists—not lists of data structures, which you can do with normal JSON, but lists that describe HTTP resources.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
I’m going to call these extra bits of design the application semantics, because they vary from one application to another. Application semantics are the cause of the semantic gap I mentioned in Chapter 1. If I were designing
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Sending a GET request to the server should have the same effect on resource state as not sending a GET request—that
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
I call this “whatever!” usage of POST overloaded POST.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
API designers shouldn’t design APIs that serve plain JSON.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
problem. In general, I don’t recommend creating new domain-specific media types. It’s usually less work to add application semantics to a generic hypermedia format—a technique I’ll cover in the next two chapters.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
registry of link relations managed by the Internet Assigned Numbers Authority (IANA). I’ll be coming back to this registry throughout the book.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
The things you’re accustomed to are dangerous.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
My experience shows that the “API call” metaphor inevitably exposes the server’s implementation details to the clients.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
This introduces coupling between server code and client code.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
The Mapmaker just keeps more application state than the Game does.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
AtomPub is the original standard for collection-based APIs, defined in RFC 5023.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
A collection is a resource that lists other resources by linking to them.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Some collection-based standards explicitly define a pagination technique. Others simply assume you know about "next" and "previous".
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
To understand those things a human must read the human-readable explanation in the prompt element. That’s how Collection+JSON bridges the semantic gap.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
If everyone used Collection+JSON for their APIs, we would all share a common definition of “collection”. But there’d be 57 different definitions of “item”, 57 sets of data elements with differing values for prompt. Some APIs would call the text field "text"; others would call it "content" or "post" or "blogPost", and they’d all describe the same thing in different words. We’d still have 57 different microblogging APIs. So we’re still not there. We still need something more.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
The main source of microdata items is schema.org, a project of four big search engines (Bing, Google, Yahoo!, and Yandex) to define application semantics for different problem domains.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
You’ve probably seen this sort of thing before: To flip a switch, send a POST request to: http://api.example.com/switches/{id}?action=flip Where {id} is the switch ID. You can only flip a switch if you are in the same cell as the switch. If you find yourself writing up (or generating) documentation like this example, you’re using human-readable documentation as a substitute for hypermedia. That’s unacceptable.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
The only human-readable documentation I need to provide is the hMaze spec, which defines the application semantics
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Siren is a newer format than HAL, and although it’s based on JSON, it takes a more HTML-like approach to hypermedia than HAL’s minimalism.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
If you use extension link relations (the ones that look like URLs), a human being who puts that URL into a web browser should find an explanation of that link relation.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Don’t Start with the Representation Format You may be tempted to choose a representation format before starting step 1, so that you can visualize what your documents will look like as you work out the semantics. It’s fine to use a general format like HTML for doodling, but I recommend you hold off on a decision until you’ve gotten, however tentatively, to step 4.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Technically speaking, none of this matters. A URL is just the address of a resource, which a client can use to get a representation.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
it’s perfectly legal for the collection of user accounts to have the URL /000000000000a, and for that collection to link to Alice’s user account using the URL /prime-numbers?how_many=200.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
The important thing is that the representation of a collection of users makes it clear that it’s representing a collection of users,
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Standard Names Are Probably Better Than Your Names
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
Most companies that put out an API never change that API after its initial release. They can’t do it. To be blunt, they can’t do it because they ignored the hypermedia constraint. Most APIs put their protocol and application semantics into human-readable
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
The more of your protocol and application semantics you can put into machine-readable form, the more ability you have to change your API without going through this slow, cumbersome process.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
XOXO Describes outlines. This microformat is interesting because it doesn’t add anything to HTML at all. It just suggests best practices for using HTML’s existing application semantics.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
API implementations should require clients to make conditional PUT and PATCH requests.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby
—
FOAF is the most famous RDF Schema ontology.
~~ RESTful Web APIs, Leonard Richardson, Mike Amundsen; Sam Ruby