Every week I run into web APIs that read like a to do list for servers, written in a hurry and hard to explain.
Let us trade mystery verbs for RESTful resources where URLs wear nouns and HTTP methods carry the verbs.
REST from a working seat is refreshingly simple once you decide the web already gave us the verbs we need, and your job is to name things. GET reads, POST creates, PUT replaces, DELETE removes, and the URL names the thing in play, which turns random endpoints into a tidy map that humans and tools can share. When your endpoint is a clean noun like users or invoices instead of makeUser or processInvoice, the mental model clicks for everyone, from the backend to the person writing docs. You can point a browser to the same address, curl it during a late night test, or wire it into a mobile app, and the intent stays clear across each hop. Caching proxies understand GET without special hints, and unsafe changes do not get cached when you stick to the verbs, so surprises shrink and pageloads get faster for free. Errors map to plain status codes, so the first clue lives in the response line rather than a mystery payload string, which cuts time during that next weird bug hunt. The payoff is clarity that travels across teams and tools with fewer meetings and less glue code, because nouns center the conversation and verbs carry the change.
Right now the Rails crowd leans hard into resources, with 2.0 making routes that speak in plural nouns feel like default city, which nudges apps toward cleaner controllers and URLs. The Atom Publishing Protocol just went stable, and it reads like a field guide for resource editing through plain HTTP, with entries, collections, and edits handled by known verbs. On the big service side, Amazon S3 talks in buckets and objects, which fits the shape, while Twitter still exposes a lot of read calls that look like resources most days. Flickr and Facebook expose method style endpoints in many places, which works, though it often hides state behind action names that clients must memorize and then defend in code. When the noun sits in the URL you get bookmarking, link hacking, and nicer logs for free, which saves time during support fires and makes troubleshooting less like archaeology. When the verb hides in a parameter your cache and your browser have less to work with, and you end up rebuilding rules that HTTP already knows and middleboxes already respect. We all want speed and predictability, and the less magic we put in custom wrappers, the closer we get to both without extra libraries or a parade of one off tweaks.
If you are moving an existing API, start by naming the real things your users care about and put those nouns in the URL tree without extra action words that repeat the method. Keep collections plural, allow each item to live at a stable address, and let related links show up in responses so clients can follow their nose and discover neighbors step by step. Use GET for reads so caches can help, return ETag or Last Modified so clients can ask politely, and make PUT or DELETE idempotent so retries are safe during outages. Favor clear status codes like 201 for a fresh resource or 409 when there is a conflict, and describe problems with a short human sentence that someone can paste into a bug. If you need versions, prefer a clean prefix or a header and keep the resource names steady, since that is what people bookmark, share in emails, and stick into scripts. Document examples beside the URLs rather than a separate theory page, and show complete flows like create list update delete with the same nouns between steps so paths stay learnable. The result feels boring in the best way, where URLs tell the story, verbs do the work, and the wire stays readable when your team changes or your traffic triples.
Good APIs age like plain text, and plain text starts with nouns that stand still and verbs that mean what they say.