Resource Naming

Naming Is API Grammar

Consumers learn your API by pattern-matching. Consistent grammar makes the hundredth endpoint predictable from the first ten; inconsistent grammar makes every endpoint a documentation trip.

The Core Conventions

 PLURAL NOUNS for collections        /trips          not /trip, /getTrips
 IDENTIFIERS as path segments        /trips/{id}     not ?trip_id= (for identity)
 ACTIONS on sub-resources            POST /trips/{id}/cancellations
 
 HIERARCHY = ownership               /drivers/{id}/trips
 FILTERS  = querying                 /trips?status=completed&city=nyc
 
 kebab-case paths                    /fare-estimates
 snake_case query params             ?pickup_time_after=
 version prefix                      /v1/trips

Verbs in URLs: When It’s Actually Fine

The “no verbs” rule bends where no resource exists:

 CONTORTED (forcing noun-shape):      PRAGMATIC:
 POST /trip-cancellation-requests     POST /trips/{id}:cancel
   {reason}                           or an explicit action endpoint
                                      POST /rides/{id}/cancel
 
 judgment: if the "resource" is pure ceremony around one action,
 model the action explicitly — consistency beats dogma

Google’s :verb convention and GitHub’s action endpoints both acknowledge reality: some operations are computations, not state.

Hierarchy Depth Discipline

 ✗ /cities/{city}/districts/{d}/drivers/{d}/trips/{t}/receipts
   → every level multiplies coupling; auth per level; caching nightmare

 ✓ /receipts?trip_id=...              flat + filter after ONE ownership level

 rule of thumb: max TWO levels of path hierarchy;
 everything deeper becomes a filter parameter

Identity Choices With Long Shadows

Choice	Example	Trade-off
Sequential ids	/trips/1043	Enumerable → leaks volume; needs authz everywhere
UUIDs	/trips/9f8e…	Non-enumerable; bigger; ugly but safe
Natural keys	/users/{email}	Breaks when the key changes — avoid

Opaque ids (UUID/ULID) are the default for public APIs: they decouple identity from meaning, enabling merges, migrations, and sharded generation later.

Query Parameter Conventions

 pagination     ?limit=&cursor=           (cursor lesson covers deeply)
 time ranges    ?created_after=&created_before=
 filtering      ?status=active&city=london
 sorting        ?sort=-created_at,fare    (- = descending)
 sparse fields  ?fields=id,status         optional bandwidth saver
 
 reserved-ish params stay consistent across ALL endpoints:
 limit/cursor/sort mean identical things everywhere — that IS the grammar

Interview Framing

Naming questions look trivial and aren’t — they test whether candidates design for consumers. The scored move: propose the collection/id/action skeleton once, then reuse it visibly across endpoints without re-deciding. Interviewers also probe edge cases (“how would you model ‘cancel’?”) expecting either sub-resource creation or an acknowledged pragmatic verb.