REST thoughts

i recently read Architectural Styles and the Design of Network-based Software Architectures, originally published in 2000.

(it's good and you should read it yourself—it's not particularly long, dense, or technical.)

i have Thoughts.

REST won§5.1, §6.3, §6.4

if you're reading these words on a web browser you're doing REST right now. URIs, status codes, the concept of headers are all 'REST'

REST is not a religion or your parents. it's a set of good ways to do things. many of those ways are good enough that other people might get mad at you if you do things differently, but no-one is making you behave

e.g. GraphQL isn't 'not REST', it just doesn't conform as much as other architectures might

Fielding goes to great lengths to emphasize that REST and other pieces of the web like HTTP were all created by different people working in different places, discretely.

there is no "web library" made by one entity that everyone has to use, there is no one language, it's just a set of standards

the possibility of non-, mis-, or malcompliance has always existed. entities have been accidentally or willfully misunderstanding and misimplementing REST since before it existed. just do your best

software

generally

components (§1.2.1) are a fantastic way to think about software

aside: evaluation generally speaking i found Fielding's methodology for evaluating architectures to be admirable but academic (derogatory). i just can't imagine doing all that in e.g. a meeting with product would actually help. maybe i'm just cynical.

a component is differentiated and discrete, defined by its boundaries, its edges, its surface, its interface.

the interface is public, the insides are private and can be changed how- and whenever

components contain other components

e.g.

your application is a component, containing your web application, email service, mobile app, etc.

your web application is a component, containing your http server, monitoring integrations, task queues, caches, etc.

your http server is a component, containing your 'create an article' handler, login/logout handlers, etc.

your 'create an article' handler is a component, containing functions that interact with the database, validate inputs, format outputs, etc.

and so forth

aside: want/have/need

i like to think about want, have, and need

one component, let's call it the caller (although it needn't be a function), wants something from another component

maybe it wants a user session, maybe it wants a list of posts, maybe it wants access to some shared memory

the other component (callee, i guess) needs certain things from the caller

maybe it needs a photo of a check, maybe it needs the value of a certain header, maybe it needs either nothing or an object or a string or between one and seven numbers

the key is to make sure the caller has what the callee needs, and the callee returns what the caller wants

it seems obvious but you'd be surprised how easy it is to forget

web-specific

a good quote

An interesting observation about network-based applications is that the best application performance is obtained by not using the network.§2.3.1.3

"Anarchic Scalability"

the section titled Anarchic Scalability§4.1.4.1 basically boils down to "your users aren't (necessarily) your coworkers"

the counterpart to "all other developers aren't (necessarily) your coworkers", noted earlier

it seems obvious but you'd be surprised how easy it is to forget

sometimes one gets a vision of Fielding's (imagined, intended) audience

when one has never not done 'RESTful' web development, one can forget that the things one needs to consider when doing 'RESTful' web development differ from the things one might need to consider when getting the robot arms to work together, or making sure people on floor 7 don't use the printer on floor 6

the S in REST stands for State

Fielding is very insistant on the client handling state

this might surprise you (it surprised me) but

the state Fielding means is the state of the interaction

basically: the client drives

e.g.: the user's browser sends a GET request with the right headers to /profile, and the server returns text that the user's brower renders as a web page, one that includes a form. the user's brower then sends a PATCH request to /profile with the right headers and body, and the server returns text that the user's browser renders as a web page that shows the updated information

the server may never PING, but only PONG

to the server, GET and PATCH are unrelated—they might happen to share certain character sequences, or result in the invocation of some of the same code paths, but it's pure coincidence

"Resources" vs "Representations"§5.2.1

we all agree organization is important, and we all agree abstractions are important, and we all agree that clarity in thought and expression is important

in this spirit, we all carve concepts out of our application, its code and its context

these concepts aren't real

whiteboards and uml diagrams and okrs and Capitalization can sometimes make us forget

the response to GET /posts/123 is not 'a post' (or even 'a Post') because there is no such thing

the response is a representation, in the form of HTML, or JSON, or something else

(content types—and the Content-Type header—are RESTful innovations)

The resource is not the storage object. The resource is not a mechanism that the server uses to handle the storage object. The resource is a conceptual mapping§6.2.3...In other words, there are no resources on the server; just mechanisms that supply answers across an abstract interface defined by resources.§6.2.4
aside: they do exist!

one component of your application may be a database, and in that database there may be a table which is labeled posts, and in that table there may be a row the primary key of which can be interpreted as 123

you will say, this is a Post

i will say: this is a row in a table in a database. where are the author bio and avatar displayed at the bottom of the HTML response? where is the truncated version of the text returned in the list view?

a row in a table in a database can hold data that corresponds to some or even all of what you and your peers mean by Post, but it is not a Post

misc

"Naturally, the quality of an identifier is often proportional to the amount of money spent to retain its validity, which leads to broken links as ephemeral (or poorly supported) information moves or disappears over time.§5.2.1.1
[T]he server receives the identifier (which identifies the mapping) and applies it to its current mapping implementation (usually a combination of collection-specific deep tree traversal and/or hash tables) to find the currently responsible handler implementation and the handler implementation then selects the appropriate action+response based on the request content.§6.2.3

this is still how it works, basically

the first non-CERN client was written in Perl§6.4.1

Perl really vanished, even more so than PHP

i'd love to read a book about what happened

HTTP/1.0 used 1 TCP connection per resource§6.3.3.1 (not just the page itself but every script, image, etc.)

in retrospect this is hiariously wasteful, on par with Philip J. Fry's oreo technique

speaking of retrospection, how did anyone ever believe in Java applets

Java, in contrast, is downloaded as binary packaged archives -- the user is therefore left to trust the security restrictions within the Java execution environment.§6.5.4.3

do you have thoughts? @ me

go home