Skip to content

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.

Infrastructures and Purposes

Infrastructure Naming Rules

Infrastructures will have a Prefix of PROD (production), NONPROD (non-production) and EXP (experimental) followed by 3 digits. Experimental infrastructures are intended to support development and testing of infrastructure changes themselves and must support regression testing of purposes and components without impacting the development of system features in NONPROD infrastructures.

Purpose Naming Rules

Purposes will have a prefix followed by 4 digits.

  • Purposes hosted in production infrastructures have prefixes:
    • LIVE to run Arda’s system for mainstream users. One of these purposes will be the one that live.xx.arda.cards will point to.
    • ALPHA, BETA, PREVIEW or similar prefixes will be introduced to expose early adopters and beta testers to new features and functionality.
    • DEMO are intended to be used for Sales demos, customer trials and similar.
    • INTEGRATION are intended to support external users test their integrations against specific versions of the system.
  • Purposes hosted in non-production infrastructures have prefixes:
    • DEV<NAME> for development purposes with <NAME> designating the engineer, team, or project that sponsors and owns the purpose.
    • TEST for system-wide testing and qualification of new functionality
    • STAGING for replication of production environments for diagnostics, testing, and qualification.
    • EXP for development and testing of significant changes to the configuration of standard Purpose instances without impacting the development of system features.

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.

Comments