Network APIs Shouldn't Force Standard Verbs

REST forces you to standard verbs like GET, POST, PUT and DELETE. This is not good.

When we model our domain, we use both nouns and verbs. Nouns are the things that exist in the system. For example, for a meeting app, calendars, events and attendees are nouns. Verbs are the actions you perform on them: you schedule an event, invite a person to an event, accept or reject an invitation, cancel an event, or reschedule it. This is how you naturally think of your domain. If you talk to a team member who’s not an engineer, like a product manager or designer, these will be the verbs they use.

When defining a network API, you want to use these natural verbs. You don’t want to be straitjacketed into HTTP verbs like GET, POST, PUT or DELETE. These are implementation details of the underlying HTTP protocol, and you don’t want to think in terms of implementation details. As an analogy, video compression works both within a frame (intra-frame) and between frames (inter-frame), but you don’t think in terms of inter- and intra- frame compression when thinking of a video. You think of a video logically as a sequence of frames. Similarly you want to think of your application in terms of verbs that make sense for the domain, like scheduling an event. Not POSTing an event. Try saying that to a UX designer and see how he’ll react.

Restricting network APIs to using standard verbs makes as little sense as forcing all method names in a Java program to be

interface Calendar {
  void get(...);
  void post(...);
  void put(...);
  void delete(...);
}

You wouldn’t design this way, would you? You’d do

interface Calendar {
  void schedule(...);
  void invite(...);
  void cancel(...);
  void markVacation(...);
}

This goes for network APIs, too.

This is a downside of REST.

I’m not against using standard HTTP verbs when they fit, like DELETE’ing an event. Just that you shouldn’t be forced into using these standard verbs when a different verb like schedule is more natural for your application domain ¹.

Interestingly, HTTP does not force you into using standard verbs. You could hypothetically make a call like:

SCHEDULE /calendars/kartick

to schedule an event on Kartick’s calendar rather than

POST /calendars/kartick

This is not RESTful but it models the domain better, and the latter is more important.

Or you could use something like gRPC which does not even use the standard HTTP verbs.

1. One advantage of standard verbs is that they define semantics. GETs are side-effect-free, so they can be cached and the next call serviced from the cache. PUTs are idempotent, so if the call fails, the RPC layer can retry it transparent to the application code.

But these benefits can be achieved with custom verbs, too. You could have some kind of a schema definition language that specifies which verbs are cacheable, and which verbs are retryable.