DEV Community: JustC

The slippery slope

JustC — Mon, 16 Feb 2026 21:00:30 +0000

Recently came across a post on LinkedIn related to query params in URI. In very simple words, the problem was related to GETting alternate representation of a resource.
Let's take an example of simple api call

Request:
GET /users/1

Response:
HTTP/1.1 200 Requested user details
Content-Type:  application/json

{"username": "Name", "displayName": "Display Name"}

If requester is only interested in displayName, the request can be made as.

Request:
GET /user/1?fields=displayName

Response:
HTTP/1.1 200 Requested user details
Content-Type: application/json

{"displayName": "Display Name"}

It looks reasonable. It works.
But what exactly are we asking the URI to represent?
The request simply means, we are looking for a way to apply projection to retrieve only the displayName and it seems legit. Is it though?

Let's look at RFC 3986, especially the part where it talks about syntax of URI or Uniform Resource Identifier.

A URI is composed of five main components, following this hierarchical pattern:

scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Scheme: The protocol used (e.g., http, ftp, mailto). It is case-insensitive.
Authority: Usually contains the host (IP or registered name) and optional port and userinfo (e.g., //www.example.com:80).
Path: A sequence of segments that identifies a resource within the scope of the scheme and authority.
Query: Non-hierarchical data, often key=value pairs, preceded by ?.
Fragment: Identifies a secondary resource within the primary one (e.g., a page anchor), preceded by #. It is processed by the user agent, not the server.

Still seems legit until you start see more such patterns

GET /users/1?fields=displayName

How about

GET /users/?sort=

GET /users/?filter=

Let's rewrite the the first example little differently

GET /users?id=1&fields=displayName

Now the oddity starts to become visible. id is, obviously, the search param, but fields is a projection. Query params sort, fields, filter, etc. are used as mini-instructions on top of limited set of HTTP verbs. People start using it, and it literally starts shaping up as a standard.

Anything wrong?

Not really. RFC 3986 is clear that stuff following "?" is just bunch of key-value pairs. In fact the entire URI is opaque, if you decipher the RFC. So much so, you would hear

a good REST API treats the query string as a structured DSL (Domain Specific Language) for the resource.

That's the beauty of ReST. Being just a guideline, you see such pragmatic shortcuts that work in real life and often more useful.

RFC allows it.
The concern is not correctness, it's architectural drift.

The Purist view

I must present a different take on the topic, otherwise this post is meaningless. The DSL keywords sort, fields, filter, etc. start crowding the limited set of verbs, and I, as a developer of API, am now forced to maintain documentation around them. Also is a fact that these mini-instructions become part of set of reserved words.

URI -> DSL
DSL -> Implicit contract
Contract -> Hidden protocol

If projection is a representation concern rather than resource selection, then HTTP already provides a mechanism: content negotiation.

GET /users/1
Accept: application/json; fields=displayName

You might have seen this in a different form as

GET /users/1
Accept: application/json; q=0.9;charset=UTF-8

The string following the media type can be used to convey additional hints about the media-type interpretation. The key-value pairs that trail the media-type are conveniently called as media-type parameters. These are open-ended too, you can have as many as you prefer, just have server implementation to process them.

You want more standard driven approach, follow RFC 6906. It adds more structure to asking for representation variations

GET /users/1
Accept: application/json; profile="http://www.example.com/profiles/user-summary"

Or you can come up with your own custom media-type

GET /users/1
Accept: application/vnd.user.displayname+json

Then why is it not used?

There are few very practical reasons rooted in the way web works.

Links are essential part of creations responses. It is much easier to convey the newly created url as

Location: /user/1?fields=displayName

than bunch of additional instructions to the client on top of regular GET. You would need to enrich the response with more headers.

Caches are not smart enough to understand these nuances. One has to sprinkle "Vary:" headers to make caches understand what to cache. It is more of hit and miss with different cache implementations.

Purpose of this post is not advocacy of purist approach. I just want to make a point that "Common practice does not automatically make it architectural practice." The roots should not be forgotten and pragmatic shortcuts must be explicitly registered as shortcuts than standard. Once the real reason for the shortcuts is forgotten, soon a slippery slope makes it faster to lose the grip of standards.

“Architecture erodes not through wrong decisions, but through forgotten reasons.”

The Seed Corn

JustC — Fri, 02 Jan 2026 19:56:12 +0000

Episode II

The first episode discussed the thinkers; this episode focuses on the doers.

This is not an argument against automation or AI.
It is an argument against mistaking acceleration for succession.

The doers

Execute -> Build -> Operate
As they work, they accumulate the tacit/tribal knowledge
Earn battle scars, and more importantly, the judgment
Over time, some transition to become "The Thinkers"

See...

The doers are thinkers in incubation

In other words

You don’t grow thinkers by hiring them.
You grow them by letting doers survive long enough to reflect.

Automation attacks the doer layer first.

Not because doers lack value, but because:

their work is observable
repeatable
specifiable

The immediate gain looks rational:

cheaper
faster
scalable

But the unseen loss is this:

You are not just removing labour...
You are removing the future thinkers.

That is the seed corn.

The missing question

AI is absolutely needed
It is powerful, efficient.

The missing point is this:

If AI is to automate the work that once trained our future thinkers, then we must deliberately invent new paths for judgment to form.

The Luxury Layer

JustC — Thu, 18 Dec 2025 19:45:13 +0000

Episode I

I would like to begin with a single-question survey:

Do you need thinkers or doers?

The likely answer is doers.
After all work won't get done just by thinking, will it?

So, are thinkers really needed?

It is a luxury to afford employing group of thinkers.

Let me clarify what I am referring to as Thinkers. You may have noticed or about to notice that in this age of AI, sooner or later, the roles or titles like Principal Engineers, Specialists, Architects, and such would be or already are reframed to be

Too narrow
Non-executional
Redundant

"Redundant" because, sooner or later, work gets detailed enough to match thinker's visions.

These visions are what:

reduce future failures
prevent scaling disasters
encode tribal knowledge

None of the above shows up cleanly in any quarterly EBITDA making it difficult to justify these roles. These roles would remain redundant until things actually start breaking.

The promotional messages to curtail thinkers is often:

We don't need thinkers anymore, we need doers + tools

No doubt AI is good, it is very useful. AI replaces

repetitive synthesis
boilerplate decisioning
low-context abstraction

But low-context abstractions is not sufficient to grasp the unsaid, the tribal knowledge. AI in its current form needs significant help to

have a systems intuition
failure anticipation
boundary judgements

I am not saying AI cant do it.
I am saying AI + a thinker would pair nicely.

The thinker roles have

long-term systems thinking
tacit, experience-earned knowledge

Replacing judgement with tools wont make systems safer.

We are entering an era where bad architecture will be shipped faster and paid for later.

Soon it is going to be frustrating for thinkers to justify the the luxury layer.

Earlier in the career justifications are part of growth and after years of grinding the justification would feel like an erasure as the value of these roles is:

cumulative
contextual
earned through scars

AI is great and people have understood its worth in

automation (tools)
Acceleration (productivity)
Judgement

First two are easy to ratify and certainly real. Judgement, on the other hand, is not. Judgement needs high context systems thinking.

Overtime AI would catch-up giving rise to newer problems expanding the context to even wider horizons.

You would notice now that value of such roles is

in the negative space (things that don't break)
their impact is delayed or not even felt
their work is preventive not demonstrative

Such work often goes unnoticed and it can feel dispensable.

ReST: Not a Silver Bullet

JustC — Sat, 22 Mar 2025 04:37:47 +0000

In previous episodes and through this series, I’ve challenged well-established notions about ReST. Now that you're drawn to ReST, hearing that it's not a silver bullet might surprise you. The intent of this series was never to pitch ReST but to inspire critical thinking. ReST is wonderful. ReST is simple. ReST is flexible. Yet, it remains one of the most misunderstood and misused styles. Using ReST to drive home a point just made sense.

Software design is a bit different from its traditional counterparts. Use cases are key to any software design, and I’m going to use a few of them to explain why ReST is not a silver bullet.

A Use Case

So, what is a use case really?

A use case is a specific situation or scenario in which a system, product, or service is used to achieve a goal. It describes an interaction between a user and the system, focusing on how the system fulfills a need or solves a problem.

What Are the Key Elements of a Use Case?

User: The individual or entity interacting with the system.
Goal: The intended outcome or purpose of the system.
System: The tool enabling the execution of the use case.
Context: The environment, circumstances, or conditions in which the use case occurs.

You’ll notice that context matters significantly and drives most of the design choices. Let’s explore a few examples to illustrate why ReST is not a silver bullet.

Real-Time Communication

Why?
ReST is strictly a request-reply design. Nothing happens unless a request is made. A ReST service cannot push notifications to its audience because it wasn’t designed for such applications.

Alternatives: You can use WebSockets or Server-Sent Events (SSE) to handle real-time communication.

Latency and Bandwidth-Sensitive Systems

Why?

ReST is stateless, making real-time communication verbose, as each request must be independent and therefore bulky. This isn’t bandwidth-friendly.

Alternatives: Use binary protocols like Protocol Buffers (protobuf) that are optimized for such scenarios. These protocols eliminate the need for headers, status codes, etc., making communication more efficient.

Inherited Non-ReST System

Why?

Sometimes, you inherit a non-ReST system and are unable to change it. This doesn’t mean you can’t improve it, but the scope might be limited to smaller features rather than a full overhaul.

Alternatives: Unfortunately, there might not be a viable alternative when you’re constrained by the system you’ve inherited. Overhauling may not be an option, so ReST might also be out of reach. However, this isn’t inherently a bad thing—it’s simply a matter of doing the job that needs to be done.

Conclusion

There are plenty of situations where ReST simply isn’t the right choice. That doesn’t mean everything we’ve discussed in this series is inapplicable. The key is to understand your use cases, determine what fits well, and then craft the interactions accordingly. The idea of viewing interactions as human-like conversations isn’t limited to request-reply styles like ReST. A similar thought process can be equally useful in event-driven architectures too.

ReST: It is more than just a CRUD over HTTP

JustC — Fri, 21 Mar 2025 13:11:55 +0000

While CRUD provides a foundational understanding of HTTP verbs, it oversimplifies ReST API design. Many argue that ReST is just CRUD over HTTP, with:

POST corresponds to creation,
GET to retrieval,
PUT to updating, and
DELETE to deletion.

While this analogy seems reasonable and works for most people, it is worth considering if there is more to it. Shoehorning a to CRUD overlooks the depth of designing systems that truly serve user intent.

In the first episode of this ReST series, I introduced a key idea:

ReST API design is like scripting a dialogue between two people

Step 1: Agree on the "Language" of the Conversation

The first step in designing a ReST API is deciding on the "language" of the conversation, essentially, the format used to exchange information. Think of it as agreeing beforehand on whether you'll "speak" in:

Plain text,
JSON,
XML, or
a brand-new format unique to your API.

This ensures that both parties, the user and the system, can understand each other clearly from the outset.

Step 2: Understand the User’s Intentions

Next, focus on understanding the requirements, which are essentially the user's intentions:

What are they trying to achieve?
What is the simplest, most natural way for them to express their request?

Step 3: Craft a Dialogue

Once you’ve understood the intention:

Formulate a request on the user’s behalf.
Craft a response that mirrors how a person would naturally reply:
- Is the response clear and precise?
- Does it provide all the necessary information?
- Does it gracefully handle errors or misunderstandings?

By treating API design as scripting a meaningful dialogue, you can create systems that feel intuitive, purposeful, and human-centric.

Now that we've established the importance of crafting meaningful dialogues, let’s take the example of order cancellation.

CRUD Way

At first glance, the user’s intention seems straightforward, they want to cancel the order. A lazy approach might map this action directly to a DELETE request.

DELETE /orders/1234

While technically valid, this design overlooks a critical aspect: understanding the “why.”

As a business owner, knowing why an order is canceled is priceless. It opens opportunities to improve services, address customer concerns, and potentially recover the relationship. A simple DELETE erases the order but loses the chance to ask the customer questions like:

Was there an issue with the product?
Was the delivery timeline too long?
Did the price feel too high?

By framing the cancellation process more thoughtfully, perhaps through a POST to a “CancelledOrders” endpoint with a reason code or message you capture the humane aspect of the dialogue. This way, the API design doesn’t just serve the technical need but also aligns with broader business goals.

Intent-Based Way

POST /CancelledOrders  
Content-Type: application/json

{
  "orderId": 1234,
  "reason": "price too high"
}

A word about nouns

CancelledOrders is a noun and at times you might need some time to come up with a meaningful noun. One may come up with a rather odd noun, OrderCanceller, and there is nothing wrong, ReST does not stop one from doing that. By the way this is a classic ReST design dilemma.

Let’s look at these two nouns systematically, balancing opinions and rationale.

Option 1: Resource Oriented (ex. CancelledOrders)

This approach treats cancellations as a distinct resource with its own lifecycle, attributes, and state, while keeping the original Order resource untouched.

Advantages:

ReSTful Purity:
- Emphasizes nouns/resources over actions, aligning with ReST's guideline of avoiding verbs in URIs.
- A CancelledOrder is conceptually distinct from an active Order, which makes this separation intuitive for consumers.
State Representation:
- Captures the cancellation reason and metadata (timestamp, actor, etc.) naturally as attributes of the CancelledOrder resource.
Extensibility:
- Provides flexibility to evolve the cancellation model independently of the Order model (e.g., add cancellation-specific rules or workflows).

Disadvantages:

Complexity:
- Introduces a new resource to manage, including relationships with the original Order (e.g., CancelledOrder must reference the Order it pertains to).
- Consumers must now interact with multiple resources to get the full lifecycle of an order.
Perceived Redundancy:
- Since cancellation is inherently an action on an order, creating a new resource for it can feel contrived.

Option 2: Action oriented (ex. OrderCanceller)

OrderCanceller does not sound English. Well, it sounds made up, most nouns are. This approach represents cancellations as an action performed on an Order, captured via a dedicated actor resource (OrderCanceller) or a simple status update to the Order resource.

Advantages:

Simplicity:
- Maintains the focus on the Order resource, which remains central to all operations (placing, updating, canceling).
- No additional resource is introduced; cancellation updates the status field of an existing Order object.
Clarity of Action:
- For consumers, "cancelling an order" as an action maps naturally to POST /orders/{id}/cancel or PATCH /orders/{id}.
Efficient Object Modeling:
- Updates occur in-place without duplicating data or introducing relationships, making implementation simpler.

Disadvantages:

Action Verb Leakage:
- Despite wrapping the action in a noun (OrderCanceller), this approach may still feel action-oriented, which some might see as less ReSTful.
Loss of Explicit History:
- If cancellations are just status changes, capturing detailed cancellation metadata (reason, actor, timestamp) requires extra fields or audit logs, muddying the core Order resource.

Balancing Opinion and Rationality

The choice hinges on whether you prioritize conceptual clarity (resource orientation) or operational simplicity (action orientation):

When to Choose Resource-Oriented (`CancelledOrders`):

Cancellation has its own business significance or lifecycle beyond being an "action" (e.g., analyzing cancellations, auditing reasons).
You expect cancellations to have complex attributes (e.g., reasons, timestamps, or even nested workflows like approvals).
Aligning closely with ReSTful principles is critical for consistency across your API.

When to Choose Action-Oriented (`OrderCanceller`):

Simplicity and operational focus are higher priorities than conceptual purity.
Cancellation is a transient state rather than a key part of your domain model.
Your system and consumers are more accustomed to action-based APIs.

Concluding thoughts

If the reason for cancellation or its auditability is significant to your business, go with CancelledOrders. It better encapsulates the separation of concerns, making cancellation its own first-class entity. This aligns well with resource-centric ReST design.
If simplicity and immediacy are paramount, and cancellation is a minor detail, use the action-oriented approach with an Order status update.

Final Note:

Nouns don’t need to sound English, but they should align with how your domain experts and API consumers naturally think. If OrderCanceller feels contrived, it might signal that CancelledOrders is the more domain-appropriate model.

Range Headers: Pagination the HTTP way

JustC — Sun, 16 Mar 2025 17:49:18 +0000

Originally published on HackerNoon, this post is now available on dev.to.

This is the second episode of the ReST series! While the first episode centered around semantics, this installment delves into the ways in which request and response headers can enhance interactions, making them more meaningful and comprehensive. For the sake of a focused narrative, we'll concentrate on a common issue: the pagination problem.

In this episode, our primary focus will be on understanding how HTTP Range headers can be employed to address the challenges associated with pagination. By narrowing our scope, we aim to provide a clearer and more in-depth exploration of this specific aspect of RESTful API design.

What Is Pagination?

Simplistically, pagination means splitting large datasets into comprehensible smaller sets and providing means to navigate across these smaller sets. An example would be, say, in some web application, a search for users yields thousands of results.

It would be impractical to overwhelm the poor soul with all results at once. First of all, the convenience of searching for large datasets is no longer a convenience, rather it is a nuisance.

Now, this post may also come as a rant as there are multiple ways to implement it, and the way I feel it should be done is not possible with current specifications.

Pagination Using Query Params

OData specification has support for pagination, and it makes use of query parameters to implement pagination. A typical OData interaction can look as below.

Request:

GET /users?$skip=0&$top=10&$inlinecount=allpages

Response:

200 Okay
X-Some-Side-Channel: count=200

Now, that’s an example of repurposing. Here, the query string is repurposed for pagination. It sounds a bit weird from the get-go. The query string, the name itself, states its purpose “for querying” and is repurposed.

There is a header prefixed X-, and such headers are called custom headers. User-agent needs to understand it, or there is a need for customization in the form of coding at the client end.

Can We Do Better?

RFC2616 had a section on content ranges as below.

14.35.2 Range Retrieval Requests

HTTP retrieval requests using conditional or unconditional GET
methods MAY request one or more sub-ranges of the entity, instead
of the entire entity, using the Range request header, which applies
to the entity returned as the result of the request

Does that sound similar to pagination?

Let’s try to model the earlier OData request using Range Retrieval Request. Ranges are resource-specific meaning /users may be a collection of more than one, user data. A single user is a unit in the collection.

Let’s Ask: What Is a Unit for Users’ Resource?

Request:

OPTION /users

Response:

200 Okay
Accept-Ranges: users

The web application is telling us that users is a unit to specify the range of users. Now, since we got to know that users is the unit, let’s ask for the first 10 users.

Request:

GET /users
Range: users=0-9

Response:

206 Partial Content
Accept-Ranges: users
Content-Range: users 0-9/200


[ 0, …, 9 ]

How does this dialogue work?

What does Request say?

In the request, the user-agent has added a Range header mentioning a specific unit discovered from earlier OPTIONS dialogue and a range in numeric form. Natural, isn’t it?

What does Response say?

The web application responds with 206 clearly stating that the response is partial. Content-Range provides details about the data in the response. In the example, 0-9/200 indicates the first 10 users’ data is being returned out of 200, the number of users satisfying the search query.

It also reiterates the unit being users as Accept-Ranges header. Since Accept-Ranges is reiterated, the OPTIONS call can be avoided altogether as the web application can simply default to sane defaults for the range parameters if the request did not send the Range header.

At times, it might be very intensive to compute the total number of records in the returned collection. In such cases, one can simply respond with * as count. So, the response looks as below.

Response:

206 Partial Content
Accept-Ranges: users
Content-Range: users 0-9/*


[ 0, …, 9 ]

You can ask for multiple ranges too.

Request:

GET /users
Range: users=0-9,35-50

Response:

206 Partial Content
Accept-Ranges: users
Content-Type: multipart/mixed; boundary=PART


--PART
Content-Range: users 0-9
[ 0, …, 9 ]


--PART
Content-Range: 35-50
[ 35, …, 50]

What if the data requested is beyond the range?

The web application can simply state that the data is not available.

Request:

GET /users
Range: users=0-9,35-50

Response:

416 Requested range is not satisfiable

But (The Rant Part)

All this discussion about Range headers might feel like a lot of talk. The potential usefulness of Range headers is, for now, mostly theoretical. While originally mentioned in RFC 2616, the specification explicitly mentions only bytes as the unit for specifying a range. It doesn't necessarily rule out the possibility of using other units, but it also doesn't affirmatively state that it is allowed.

Even in the latest specifications on HTTP, namely RFC7231 and RFC7233, the stance remains unchanged. In reality, the sad truth is that as of now, there are no HTTP servers with native support for custom range units. It is like having a tool in the toolbox that looks promising on paper but turns out to be rarely used in practice.

Whether this will change in the future or if the theoretical potential of Range headers will forever remain just that - theoretical - only time will tell.

ReST: The Need to Talk

JustC — Wed, 05 Mar 2025 16:03:11 +0000

Originally published on HackerNoon, this post is now available on dev.to.

In the history of human existence, communication serves as the indispensable thread that weaves connections, understanding, and knowledge. Picture this: in a corner of the comic world, on November 7, 1989, Calvin from Calvin and Hobbes engages in a conversation with his dad over the phone. This seemingly ordinary scene encapsulates a universal truth

– the need to talk.

No one is omniscient, see Calvin didn't know 11 + 7. The complexities of life, the myriad of experiences, and the wealth of information that surrounds us demand an incessant quest for understanding. We need to talk to others, at times, to seek answers, perspectives, or simply to share our thoughts. However, this act of communication is not haphazard; it follows a set of unspoken rules, guidelines, and etiquette that transform it into a nuanced art. Communication is, in essence, the bridge that connects minds, allowing ideas to flow, emotions to be shared, and knowledge to be transferred. Yet, mastering this art is no small feat. The intricacies of language, the subtleties of tone, and the all those non-verbal cues all contribute to the richness of human interaction.

Now, as a coder, I find a parallel allure in translating this intricate communication into the realm of machines talking to machines. In the vast landscape of programming, where precision and clarity are paramount, communication takes a different form.

API

An acronym for "Application Programming Interface", though sounding just too technical, is just a term for machines talking to machines. As with any communication, there are varied kinds of it too. SOAP (Simple Object Access Protocol), ReST (Representational State Transfer), RPC (Remote Procedure Calls), etc. just to name a few.

It is worth noting that communication in the digital realm isn't confined to APIs alone. There's also the intriguing realm of event-driven communication – an asynchronous data exchange that doesn't always wear the API label prominently. Yet, it plays a crucial role in orchestrating seamless interactions between different components, making systems agile and responsive.

ReST

I have been dealing with web-apis, flavors of ReST, for almost two decades now. And I say flavors of ReST as ReST is not as stubborn as other such protocols as SOAP simply because it is not a protocol, rather just set of guidelines or architectural style.

That sets ReST apart from others in very distinct way. ReST makes machine-to-machine communication more humane, simple and natural. Detailing a ReST api is more philosophical than technical, because one always starts with nouns when designing a ReST api.

What's in the Name?

Seriously what’s in the name? why are we so obsessed with names and naming things? I had blogged about it a decade ago. It was and still is an opinion of mine that names are nothing more than an abstraction to details. Without names conversation would be too wordy, verbose and still not very clear. We tend to name things and to make things clearer, we add more discriminating names. More the number of nouns, richer the vocabulary. Eskimos have twenty odd names for different kinds of ice. Names are not just limited to things or places, but also cover many actions.

Actions

But there is a stark difference between names and action. If names and actions are a sets, mathematical sets, you would notice cardinality, number of items in the set, of names increases overtime whereas same is not true for actions. Cut as an action has same name when you are cutting a paper as well as cutting vegetable. Actions, thus, are polymorphic in nature. Same action can be tied to multiple nouns.

HTTP

Enough with philosophy, let’s now focus on technicality. ReST came along with HTTP, and it is hands-in-glove relation. There are few misunderstandings about HTTP, mostly about usage. Most folks look at HTTP as a Transport protocol, they are not to blame though, you can download files with HTTP, so one can easily fall for it. Confusion of HTTP being a Transport protocol stems from the fact that the acronym or abbreviation literally is

Hyper-Text Transfer Protocol

When you perform an action using HTTP, it usually involves some sort of Document Shuffle, you are either sending a document to, or receiving one from, a server. The word you really want to focus on is Hyper-Text. Since most of the time the substance of a sentence is usually in the middle, unfortunately many fell for Transfer than Hyper-Text and synonymously used Transport in place of Transfer wherein both are literally different terms.

The fact is HTTP is “Application Protocol”

It works on top of real transport protocols as TCP/IP (Connection Oriented) or UDP or QUIC (Connection Less) in case of HTTP2.

HTTP Verbs (Methods)

To shuffle a document HTTP defines very few verbs limited to GET, PUT, DELETE and POST

GET is to fetch a document
PUT is to place a document
DELETE is to remove a document
And let’s not talk about POST just yet, let's circle back to it later.

A Dialogue

Above image depicts a simple dialogue between a user and some web application. Each message in this dialog is some sort of document being shuffled between the parties. Let's not worry about what's shuffled for now. It traces a workflow for the web-application.

Media Types

The data which is getting shuttled between server and the user follows certain agreed upon format so both parties can make sense of it. This formatting is dictated as Media Type. Let’s look at few examples.

text/plain
text/html
image/jpeg
application/xml
application/vnd.example+xml

Looks familiar, except may be the last one and I am not referring to the formatting.

Let’s read the last media type

application
The media is for consumption by an application not humans
vnd
This is vendor defined custom media type.
example
This is a vendor specified media type name
+xml
This media type is based on already known xml media type

Hyper-Media Types

We have seen media types now what does Hyper mean? User uses some application which talks to server on user’s behalf. The applications employed by users are referred as user-agents. The web browser is an example of user-agent. These user-agents understand and make sense of the media which flows to and from the server.

A Nudge

An application at the server must have an agenda as the conversation needs to have a closure. It must end either successfully or unsuccessfully. As with any dialogue user-agent and application on the server take turns to take next step as per the selections by the user-agent, in fact on behalf of the user. Web application is just simply nudging the user to have a closure on ongoing interaction.

Consider following interaction which depicts one request-reply.

Request

POST /orders
Host: example.org
Content-type: application/vnd.example+xml
Accept: application/vnd.example+xml

<order xmlns=“http://schemas.example.org/”>
  <item qty=“2”>ITEM-1</item>
</order>

Reply

HTTP/1.1 201 Order created
Location: http://example.org/orders/1234
Content-Type:  application/vnd.example+xml

<order xmlns=“http://schemas.example.org/”>
  <item qty=“2”>ITEM-1</item>

  <next xmlns=“http://schemas.example.org/state-machine” 
    rel=“payment”
    uri=“http://example.org/orders/1234/payment”
  />

  <next xmlns=“http://schemas.example.org/state-machine”
    rel=“self”
    uri=“http://example.org/orders/1234”
  />
</order>

Let's see what a browser, the user-agent, is sending as a request

Request Method
One of HTTP verbs. In above request it is POST
Request URI
URI of the resource. In above request it is /orders
Request Headers
Accept lets the server know what media type user-agent is interested in
Content-Type
Tells the server the data, being sent in the request, is in what format
Request Body
And finally the data which is being sent to the server.

Let’s breakdown the response received from the server

User-agent coordination
It talks about the consequence of the request
- HTTP/1.1 201 Order created 201 is a status code telling the user-agent that request has been successfully executed and as a consequence a resource is being created. Now resource may sound too technical but in reality what it simply means a new object is created on the server.
- Location: http://example.org/orders/1234 Location is a response header. It tells user-agent, if interested, it can follow the link in the header and redirect the user-agent to, in this case, to newly created resource.
- Content-Type: application/vnd.example+xml It simply tells the user-agent that the data which is being sent to it is using application/vnd.example+xml media type.
The media

or the data itself, rest of the bytes sent by the server are simply the actual data.

Now since the media type in this case is a custom one, it all depends on user-agent to make sense of it. In the example, user-agent may be smart enough to parse the response data and

Proceed to payments
Or simply interact with the newly created order resource.

In either case user-agent may use various HTTP verbs to interact with these resources.

Server is simply nudging the user, via the user-agent, to finish up the workflow of placing an order.

Since there are more than one outcomes of the decision taken by user-agent there are few possible interactions.

Say user wants to cancel the order

Request

DELETE /orders/1234
Host: example.org
Accept: application/vnd.example+xml

Reply

HTTP/1.1 200 Okay
Content-Type:  application/vnd.example+xml


<order xmlns=“http://schemas.example.org/”>
  <item qty=“2”>ITEM-1</item>
  <status>Cancelled</status>
</order>

Or user wants to proceed with payment

Request

POST /orders/1234/payment
Host: example.org
Content-Type:  application/vnd.example+xml
Accept: application/vnd.example+xml


<payment orderId=“1234” xmlns=“http://schemas.example.org/”>
…
</payment>

Reply

HTTP/1.1 201 Receipt generated
Location: http://example.org/orders/1234/receipt
Content-Type:  application/vnd.example+xml


<order xmlns=“http://schemas.example.org/”>
  <item qty=“2”>ITEM-1</item>

  <status>Not Ready</status>

  <next xmlns=“http://schemas.example.org/state-machine”
    rel=“self”
    uri=“http://example.org/orders/1234”
  />
</order>

In all these interaction user is presented with enough coordination and the media itself to be able to proceed with successfully completing the workflow.

In case user-agent followed payments and it was successfully processed, as a side-effect receipt would be generated. Coordination data says so by 201 and gives uri to receipt as Location header. Client can now poll the self uri to see if order is ready.

Polling may sound stupid, but it is extremely effective with use of caches. These caches lessen the burden on the server as more often order is simply not ready immediately as it takes time to work with the order.

Curious case of POST

Important point is client has some part of application state locally cached or cached along the chain.

Now about the POST which was introduced in subtly different way. I am treating it post other verbs. Creations are mostly associated with POST, when in fact GET followed by a PUT can do the job.

For example creating a new order can be a series of operations as

GET last order
Create new order locally and Put back the new order

Then why POST?

Answer is quite obvious, I am merely making it explicit now. One important thing to note is that such applications are, typically, multi-user applications.

Let's say new order-id is a function of number of orders in the collection + 1. Since it is multi-user application there can be more than one users simultaneously wanting to create new order. All these users ask, GET, for last order-id and all will end up with same. When these users PUT new order, last person to do so wins. Users come to know about failure or success only by GETting the order by order-id and verify it with locally created order. Failed users simply must redo the same sequence till they succeed. Rather if users just let the server know of their intention of creating a new order and the almighty server having wholistic application state would be in better know-how to process the requests. GET / PUT / DELETE or any sequence of it would not be sufficient to express such intent so POST. No wonder it sounds and feels alien.

Cache Consistency

Caches introduce a consistency problem though. Say, client has been told to cache a response for few seconds and meanwhile order is ready. Client, based on the cached response, decided to cancel the order. In this case client and server state has diverged. To make it safe to cancel, client can add a condition in the form of If-Match header. Server, in case where the condition does not match simply refuses to process the request telling client that the precondition to honor the request has failed. In the unlikely event, client did not send the If-Match headers, server can still report it as 409 conflict. Or 406 not acceptable.

Request

DELETE /orders/1234
Host: example.org
If-Match: status=Not Ready
Accept: application/vnd.example+xml

Reply

HTTP/1.1 412 Precondition failed.
Content-Type:  application/vnd.example+xml


<order xmlns=“http://schemas.example.org/”>
  <item qty=“2”>ITEM-1</item>

  <status>Ready</status>

  <next xmlns=“http://schemas.example.org/state-machine”
    rel=“self”
    uri=“http://example.org/orders/1234”
  />
</order>

Cancelled the order but Why?

As a business user, wouldn’t you want to know why was the order cancelled? These reasons are beyond api designing and delve more into business asks. If the api has implemented DELETE to cancel the order a typical interaction may look as bellow.

Request

DELETE /orders/1234
Host: example.org
Accept: application/vnd.example+xml

Reply

HTTP/1.1 200 Okay
Content-Type:  application/vnd.example+xml


<order xmlns=“http://schemas.example.org/”>
  <item qty=“2”>ITEM-1</item>
  <status>Cancelled</status>
</order>

Problem with above interaction is that DELETE does not accept any body. How can we solve this?

Let’s try using POST

Request

POST /orders
Host: example.org
Accept: application/vnd.example+xml


OrderId=14
&Operation=Cancel
&Reason=Just to annoy you

Reply

HTTP/1.1 200 Okay
Content-Type:  application/vnd.example+xml


<order xmlns=“http://schemas.example.org/”>
  <item qty=“2”>ITEM-1</item>
  <status>Cancelled</status>
</order>

This does not even look right from the get-go. Feels like we are performing a business operation specified by Operation. Operation is now a keyword which needs to be handled beyond limited set of HTTP verbs. This way the api would keep on adding more and more verbs which need special handling.

Can we do better?

Once we start constraining ourselves to only four verbs which HTTP provides, we can definitely do better. Let's revisit the same problem with the api designing constraints.

Do not forget that you have limitless supply of nouns. And we are naturally wired to produce random names all the time.

Request

POST /CancelledOrders
Host: example.org
Accept: application/vnd.example+xml


OrderId=14
&Reason=Just to annoy you

Reply

HTTP/1.1 200 Okay
Content-Type:  application/vnd.example+xml

<order xmlns=“http://shemas.example.org/”>
  <item qty=“2”>ITEM-1</item>
  <status>Cancelled</status>
</order>

Though it sounds simple to come up with names, it is very tedious. No wonder diehard proponent of ReST, Mark Baker or Tim-Berners Lee, suggested to not add any meaning to URI and making them opaque.

Opaque URIs relieves us from the need to produce new nouns every now and then at the cost of comprehensible api. This also makes documenting the api difficult as api end-points are decided at run-time. Also, security and relevant features can only be useful once the opaque uris are established.

Roy Fielding, on the other hand, has an opinion that uris are meaningful and it sort of makes more sense. Opaque URIs are for lazy folks.

Representations

Now let's focus on Re of ReST. It is not the resource which is sent to the user-agent. User-agent asks for specific type of media it can understand. Let’s consider following HTTP interaction.

Request

GET /orders/1234
Host: example.org
Accept: text/plain

Reply

If the web-application does not understand the requested media type, it can simply state this inability as

HTTP/1.1 415 Unsupported Media Type.

Or if it does indeed support the requested media type

HTTP/1.1 200 Okay
Content-Type: text/plain


Order 1234 is not ready

If user-agent requests for media types which are supported by the web application, it can send the resource data fitting the requested media type. Here it is the same resource but formatted as different media types and all these variations of same resource is called representations. Since the data which flows between the user-agent and the server can be different representations, it is known as Representational State Transfer or simply ReST.

Further Reading
Roy Fielding’s dissertation

DEV Community: JustC

The slippery slope

Anything wrong?

The Purist view

Then why is it not used?

The Seed Corn

Episode II

The missing question

The Luxury Layer

Episode I

ReST: Not a Silver Bullet

A Use Case

What Are the Key Elements of a Use Case?

Real-Time Communication

Latency and Bandwidth-Sensitive Systems

Inherited Non-ReST System

Conclusion

ReST: It is more than just a CRUD over HTTP

Step 1: Agree on the "Language" of the Conversation

Step 2: Understand the User’s Intentions

Step 3: Craft a Dialogue

CRUD Way

Intent-Based Way

A word about nouns

Option 1: Resource Oriented (ex. CancelledOrders)

Advantages:

Disadvantages:

Option 2: Action oriented (ex. OrderCanceller)

Advantages:

Disadvantages:

Balancing Opinion and Rationality

When to Choose Resource-Oriented (CancelledOrders):

When to Choose Action-Oriented (OrderCanceller):

Concluding thoughts

Final Note:

Range Headers: Pagination the HTTP way

What Is Pagination?

Pagination Using Query Params

Request:

Response:

Can We Do Better?

Let’s Ask: What Is a Unit for Users’ Resource?

Request:

Response:

Request:

Response:

How does this dialogue work?

What does Request say?

What does Response say?

Response:

Request:

Response:

What if the data requested is beyond the range?

Request:

Response:

But (The Rant Part)

ReST: The Need to Talk

API

ReST

What's in the Name?

Actions

HTTP

Hyper-Text Transfer Protocol

HTTP Verbs (Methods)

A Dialogue

Media Types

Hyper-Media Types

A Nudge

Request

Reply

Request

Reply

Request

Reply

Curious case of POST

Cache Consistency

Request

Reply

Cancelled the order but Why?

Request

When to Choose Resource-Oriented (`CancelledOrders`):

When to Choose Action-Oriented (`OrderCanceller`):