1. Purpose

This guideline defines how APIs must be named in order to ensure consistency, clarity, uniqueness, and discoverability across the enterprise.

The objective is to make API names understandable for developers, tech leads, system owners, architects, and API consumers.

2. Scope

This guideline applies to API products published in the API management ecosystem as trusted and reusable APIs.

It applies in priority to internal APIs managed within the SAIL / API management context.

External or third-party APIs may be referenced in the catalog, but they are subject to specific naming exceptions.

Backend APIs dedicated to serving a specific front-end application (non-reusable / "Backend-for-Frontend" style APIs) should also attempt to follow this naming convention as much as possible. Rationale: if the API becomes reusable in the future, its name will already comply with the enterprise standard and will not require renaming.

3. Naming principles

API names must follow these principles:

• Be unique within the API management ecosystem.
• Be self-explanatory.
• Use official enterprise reference values where applicable.
• Support searchability and readability.
• Distinguish the API product name from endpoint names and operations.
• Support future reuse, including for APIs initially built to serve a single front-end application.

Mandatory rules

4.1 General rules

• API names must be unique.
• API names must be self-explanatory.
• The word "API" must not be included in the API name.
• Environment names must not be included in the API name (for example: "dev", "tst", "int", "uat", "prd").
• Business domain names must come from the official enterprise reference repository Confluence link.
• Application names must come from the official enterprise reference repository (CMDB / ServiceNow).
• Ad hoc or locally invented domain values must not be used.
• Backend APIs dedicated to a single front-end application (non-reusable / BFF) should still attempt to comply with this naming convention to anticipate future reuse.

4.2 Separator rule

Hyphens ("-") must be used as the standard separator between naming components (source, business-domain, functional-object, technical-name, region). They MUST NOT be replaced by any other character for component separation.

4.3 Product name vs endpoint name

The API product name identifies the API as a reusable product in the catalog. Endpoint paths, operations, and CRUD actions are not part of the API product name. Names such as "get-account", "create-ticket", or "update-contract" belong to endpoint definitions or operations, not to the API product name itself. In published URLs, the API product name is typically used as the API base path.

Examples:

• API product name: scor-finance-account
• API base path: https://sail-apim-eu.eu.scor.local/scor-finance-account
• Full endpoint example: https://sail-apim-eu.eu.scor.local/scor-finance-account/v1/accounts/{accountId}

4.4 Front-end serving backend APIs

Backend APIs serving application front-ends, even when not initially intended for reuse, should aim to follow this naming convention as far as possible. This ensures naming consistency across the landscape and avoids renaming effort if such APIs later become reusable, trusted, or published through the API management ecosystem.

5. Standard naming pattern

5.1 Internal APIs

The default naming pattern for internal APIs is:

<source>-<business-domain>-<functional-object>[-<technical-name>][-<region>]

Where:

• <source> identifies the source / ownership context.
• <business-domain> identifies the official business or functional domain.
• <functional-object> provides additional functional context based on Domain-Driven Design (DDD). It should name the main business object or capability exposed by the API in its functional domain.
• <technical-name> identifies the official application name.
• <region> provides geographical or organizational scope when required.

6. Naming components

6.1 Source

The source component identifies the source or exposure type of the API.

Typical values include:

• scor for internal SCOR-managed APIs
• ext for external / third-party APIs
• Additional values may exist if formally governed and approved.

6.2 Business domain

The business-domain component must use the official enterprise domain name from the CMDB / ServiceNow reference.

Examples of domain values: finance, pc, lh, hr, risk, investment, transversal (exceptional value; must be validated with the Architecture Team before use).

These examples are indicative only. The authoritative source remains the enterprise reference repository.

6.3 Functional object

The functional-object component represents the main business object or business capability exposed by the API within the scope of the selected business domain. It follows a Domain-Driven Design (DDD) approach and should therefore reflect the terminology used in the relevant bounded context, rather than a technical implementation detail.

The functional-object MAY consist of multiple DDD functional terms when required to express a composite business capability. When multiple functional terms are used:

• underscores ("_") MAY be used to separate terms inside the functional-object;
• hyphens ("-") MUST NOT be used to separate internal functional terms, as they are reserved for naming component separation.

Examples discussed in current working material include: account, contract, claims, document, sanctions, treaty_risk_pricing.

Temporary fallback values may be used only by exception when no stable domain-specific business object can yet be identified: data, cross. Such values must be validated with the Architecture Team and reviewed later when the API scope and target reuse perimeter become clearer.

This component should be used when it adds meaningful functional clarity.

6.4 Technical-name

The technical-name component is optional and must use the official application name (technical name) from the CMDB / ServiceNow reference. If the technical name contains "-" or a blank space " " or other special character, replace it with an underscore "_".

Examples: omega, alpha, servicenow, peopledoc, bridger, watchdog. These examples are indicative only.

The underscore character ("_") is reserved for replacing unsupported characters inside the technical-name component. The authoritative source remains the enterprise reference repository.

6.5 Region

The region component is optional and should only be used when regional differentiation is required.

Examples: eu, us, apac.

7. External / third-party APIs

External or third-party APIs do not fully follow the same rules as internal APIs, because their underlying design and naming are not fully controlled internally. When such APIs are published or referenced in the API catalog:

• their naming must be reviewed and validated before publication or reuse;
• the naming should remain pragmatic and understandable;
• exceptions must be documented when strict alignment with the standard pattern is not possible.

8. Examples

8.1 Internal API examples

• scor-finance-account
• scor-corporate-sanctions-vasarely-eu
• scor-pc-claims-alpha
• scor-pc-treaty-eu
• scor-pc-treaty_risk_pricing

8.2 External API examples

• ext-salesforce

8.3 Full endpoint example (illustration)

The API name is used as part of the gateway endpoint URL:

• https://sail-apim-eu.eu.scor.local/scor-finance-account
• https://sail-apim-eu.eu.scor.local/scor-pc-claims-alpha

9. Governance

This naming convention must be governed centrally. The following reference lists must be maintained in enterprise reference systems:

• approved source values;
• official business domains;
• official functional objects;
• official application names;
• approved exceptions where applicable.

The API naming convention must not be managed only locally within one project or product team.

10. Related guidelines

This naming convention complements, but does not replace:

• API design guidelines for endpoint paths and resource naming;
• OpenAPI documentation standards;
• API publication and lifecycle governance rules.