Prepositions such as “with,” “to,” and “for” can make API names readable, but they may also expose an underlying design problem. In resource names, “with” often signals that a response needs optional related data rather than a new resource type. section 3.3.2
Books with related resources
Suppose a Library API lists Book resources and includes their Authors. A resource named BookWithAuthor and an RPC named ListBooksWithAuthors may work initially, but adding Publishers or both relationships multiplies specialized RPCs. Use a field mask or view to select included attributes instead of encoding every combination in a resource name. section 3.3.2
Apply these naming checks:
- Treat prepositions as design signals, not automatically forbidden words. section 3.3.2
- When “with” describes selectable response content, prefer a field mask or view over a new combined resource. section 3.3.2
- Keep legitimate domain names possible; prepositions may still fit fields such as bits_per_second. section 3.3.2
