Resources and names

An account, a project, a website, a page, a block, a menu item, a media file, a setting: a persisted thing with an identity, addressed by a name that spells out where it sits.

The name is the handle to store — not the URL, which carries a host and a version that may change, and not the display_name, which is a label a person edits. Given a name, the URL it is served at is a prefix away, which is why a client that keeps names can walk the hierarchy without a table of endpoints:

Code
account=$(curl_json "${auth[@]}" "$TENANT_API/tenant-api/v1/accounts" | jq -r '.accounts[0].id')
project=$(curl_json "${auth[@]}" \
  "$TENANT_API/tenant-api/v1/accounts/$account/projects" | jq -r '.projects[0].id')
website=$(curl_json "${auth[@]}" \
  "$TENANT_API/tenant-api/v1/projects/$project/websites" | jq -r '.websites[0].id')

site="$TENANT_API/tenant-api/v1/websites/$website"

5. Resources and resource names

A resource is a persisted thing with an identity. A collection is a set of resources of one type, addressed by a plural snake_case id.

A resource name is the path from the root collection to the resource, with no leading slash and no version:

Code
websites/6a5e4957db9aab43d50bfd35
websites/6a5e4957db9aab43d50bfd35/cms_pages/507f1f77bcf86cd799439011
websites/6a5e4957db9aab43d50bfd35/cms_pages/507f1f77bcf86cd799439011/views/68b0c1
websites/6a5e4957db9aab43d50bfd35/settings/general.locale.default_language
accounts/64f0.../projects/64f1...

Rules:

• Collection ids are plural, snake_case, and identical to the path segment, the name field, and the List-response array field. One spelling.
• Names alternate collection id and resource id, always starting with a collection id and ending with a resource id (a singleton ends with its singular collection id — §9).
• A resource id is opaque to clients. Ours are Mongo ObjectIds, except settings, whose id is its dotted path, and views, whose overlay id is the view it overlays.
• Every resource MUST carry its own name in an output-only name field, and MUST also carry id — the final path segment, output-only. id is a documented convenience (D3); name is the identity.

6. URL mapping

A resource name maps to a URL by prefixing the surface and the version:

Code
{surface}/{version}/{resource_name}

so websites/{w}/cms_pages/{p} is served at /tenant-api/v1/websites/{w}/cms_pages/{p}, and a collection is the same URL truncated after the collection id.

• Path parameters MUST be snake_case and MUST match the field they carry: {website_id}, never {websiteId}.
• A URL MUST NOT contain a verb as a path segment. Verbs are custom methods and use the : separator (§10).
• A URL MUST NOT contain a file extension.
• No trailing slash. A request with one gets 301 to the canonical form.