Skip to main content

API & Service Naming

Universal Rules​

These apply regardless of protocol:

  • Name resources, not actions. The transport (HTTP method, RPC verb) expresses the action. The name should identify the thing being acted on.
  • Use domain language. Order, Fulfillment, Shipment — not DataObject, Record, or Item.
  • Version explicitly. Include a version in your API surface (v1, user.v1) from the start. Adding it later is a breaking change.
  • Be consistent. If one service uses userId, every service uses userId — not user_id, uid, or userIdentifier.

DNS & Addressing Schemes​

Establish a token set and apply it uniformly across all APIs and DNS names:

TokenDescriptionExample
{comp-name}Company nameacmeco
{org-name}Organizationretail, mfg
{sol-name}Solution / productshopping, inventory
{app-root}Root resourcecart, skus
{app-route}Sub-resourceitems

Unified (single apex domain)​

api.{comp-name}.com/{org-name}/{sol-name}/{app-root}/{app-route}

api.acmeco.com/retail/shopping/cart/items
api.acmeco.com/mfg/inventory/skus/items

Separated by organization​

{org-name}.api.{comp-name}.com/{sol-name}/{app-root}/{app-route}

retail.api.acmeco.com/shopping/cart/items
mfg.api.acmeco.com/inventory/skus/items

Pick one pattern and apply it everywhere. Mixing them across teams defeats discoverability.

Technology-Specific Conventions​