Naming of Hosts and Routes in Arda Platform.

URL Classifiers¶

Arda’s Platform Runtime is a hierarchy of Infrastructures, Purposes, and Components and at the same time there are distinct use cases that drive access to Arda’s platform. These two classifications inform the names and structure of public URLs that give access to Arda’s platform.

Capability Classifiers¶

There are three main use cases to support in the public access points:

End-user applications: These are UI based applications that end-users will use to interact with the platform. They will be hosted in the app domain.
API’s: These are API’s that expose the functionality of the platform. They will be hosted in the io and api domains. In the long term, the api domain will be the main one and the io domain will be deprecated. Currently, (April 2025), GoDaddy hosts the api domain and migrating it would disrupt current users.
OAuth2.0 Authorization Endpoints: These are the endpoints that will be used to authorize access to the platform. They will be hosted in the auth domain.

The Arda System offers functionality in API Endpoints supported by its different modules, potentially in different versions. These endpoints will be expressed as paths in the URL.

Structural Classifiers¶

The hierarchy of Infrastructures and Purposes gives an orthogonal classification of URLs. Different combinations of Infrastructures and Purposes may expose the same capabilities. For example, the same API may be exposed in different Infrastructures and Purposes. The combination of these two classifiers gives a unique name to each URL.

Infrastructures don’t currently expose any external network interfaces. Purposes define the system-wide names to access functionality and Component define the specific routes that are provisioned in their hosting Purpose based on the Endpoints (Functional Concept) of the modules they host.

URL Structure and Naming¶

The general URL structure:

https://<Purpose>.<Infrastructure>.<capability>.arda.cards/<major-version>/<endpoint-name>/<specific-route>

Where:

<Purpose> is the name of the Purpose that is hosting the instance of Arda’s system.
<Infrastructure> is the name of the Infrastructure that contains the Purpose.
<capability> is the name of the type of capabilities offered. It can be app, io, api, or auth.
<major-version> is the SemVer major version of the API definition (not the module or component version).
<endpoint-name> is the name of the endpoint in the Functional Viewpoint of the architecture. This should follow the REST naming conventions and standards as much as possible.
<specific-route> is the route, as understood in OpenApi Specifications of the API Endpoint.

Canonical Capability Names¶

We will provide stable names for the standard released version of the product. These names use the live prefix for each capability. They do not include specific Infrastructure or Purpose identifiers.

live.app.arda.cards
live.io.arda.cards
live.api.arda.cards
live.auth.arda.cards

Standard Infrastructure and Purpose Names¶

There are two distinct types for Infrastructures: PRODUCTION and NON-PRODUCTION, the first kind is intended for access by users and systems outside of Arda’s company and subject to strict contractual and Service Level Agreements. The second kind is intended for internal uses like development, testing, etc.

Infrastructure Naming Rules¶

A runtime infrastructure name has 3 parts, a kind, a qualifier, and a revision, joined by a ..

The kind classifies the infrastructure according to its high-level usage. There is a short list of kinds; at the moment
we have:

Prod infrastructures are used primarily to support the Arda company and have high availability and reliability requirements.
NonProd infrastructures are used for development and testing of production-like scenarios.
Sandbox infrastructures are used for one-off transient environments for experimentation and exploration.
Sandbox infrastructures are owned by a single individual or a small team.

The qualifier assigns the infrastructure to a specific product or project. The qualifier is a short name that identifies
the product, project, or owner that the infrastructure supports. While some qualifiers may be shared across multiple
infrastructures, others may be unique to a single infrastructure.
Examples

amm for the Arda Money Making product (aka Arda Cloud), applies to NonProd and Prod kinds.
oam for the OAM product, applies to NonProd and Prod kinds.
kyle for Kyle’s personal sandbox environment, applies to Sandbox kind only.
infra for infrastructure testing environments, applies to Sandbox kind only.

These examples are informative and not normative; the actual qualifiers in use may differ.

The revision is a three-digit number that allows for multiple sequential environments of the same kind and qualifier
when major infrastructure changes are needed that require a new environment to be created.

Purpose Naming Rules¶

Purposes will have a short name.

At the moment, we have the following standard purposes:

dev: Development purpose, used for active development of features.
stage: Staging purpose, used for pre-production testing and validation.
demo: Demonstration purpose, used for showcasing the product to potential customers.
prod: Production purpose, used for live, customer-facing operations.
live: Canonical purpose name for production operations, it is an alias to prod.

Other purposes may be defined as needed, but they should follow the same naming conventions.

API Endpoint Naming Rules and Versioning¶

API Endpoints will follow Semantic Versioning 2.0 SemVer. While their versions will be related to the version of the module that implements them and the version of the component that deploys them, these three versions are not the same and will be managed independently. The version used in the URL will be the major version of the API Endpoint.

API Endpoints will be named in a way that is URL encoding friendly and all lowercase. They should match a regex of the form ^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$ (kebab case starting with a letter). They should also follow the REST conventions and standards as much as possible:

Use the plural form of the resources they manage.
If they are special purpose endpoints (e.g., pdf-render, qr-lookup) the name should be mnemonic of the functionality it provides.