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. URI
s, 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
components
(§1.2.1) are a
fantastic way to think about software
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
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
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
An interesting observation about network-based applications is that the best application performance is obtained by not using the network.§2.3.1.3
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 'REST
ful' web development,
one can forget that the things one needs to consider when doing 'REST
ful' 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
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
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 REST
ful
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
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
"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
© 2025 sam raker