.. _core-api-conventions:

Conventions
-----------

This page describes the conventions the Core API follows. It is
intended to help you read the OpenAPI specification and predict how
the API behaves across endpoints.

Operation identifiers
=====================

Every operation in the spec carries an ``operationId`` — a unique
symbolic name in **camelCase** (e.g. ``getCp``, ``listCards``,
``createReservation``).

You can use the ``operationId`` as:

* a stable anchor when linking to a specific endpoint in Swagger UI,
* the method name produced by SDK generators
  (OpenAPI Generator, Speakeasy, Postman code-gen, …),
* a precise identifier when reporting issues to support.

The format is ``<verb><Resource>``:

==============  =====================================================
Verb            Meaning
==============  =====================================================
``get``         Retrieve a single resource by its identifier
``list``        Retrieve a collection (paginated or unbounded)
``create``      Create a new resource
``update``      Replace an existing resource
``patch``       Partially update an existing resource
``delete``      Remove an existing resource
``<action>``    Action-style endpoints use the action as the verb —
                e.g. ``exportChargeLog``, ``triggerRemoteStartAttempt``,
                ``validateVat``, ``changePassword``,
                ``downloadInvoice``
==============  =====================================================

A few examples mapping path → ``operationId``:

* ``GET /cp/{uuid}`` → ``getCp``
* ``GET /cards/{contact_uuid}`` → ``getCards``
* ``POST /charge_log_export/`` → ``exportChargeLog``
* ``POST /remote_start_attempt/trigger`` → ``triggerRemoteStartAttempt``
* ``GET /contact_kpi/dashboard_stats/{contact_uuid}`` →
  ``getContactKpiDashboardStats``

Path parameters
===============

Path parameters use ``snake_case`` (e.g. ``{cp_uuid}``,
``{contact_uuid}``, ``{rate_id}``). Where the resource type is
unambiguous from the path, the parameter name reflects the resource
type (``{cp_uuid}`` rather than the generic ``{id}``).

Query and body parameter casing
===============================

For historical reasons, query and body parameters in v1 use a mix of
``snake_case`` and ``camelCase``. The exact casing of each parameter
is documented per-operation in the OpenAPI spec — refer to the spec
for the authoritative name.

Standard formats
================

Where applicable, the spec uses OpenAPI standard ``format`` keywords
so that SDK generators and validators can interpret values correctly.
The wire payload remains a JSON string in every case.

===============  ===============================================
``format``       Used for
===============  ===============================================
``uuid``         Resource identifiers shaped like
                 ``"550e8400-e29b-41d4-a716-446655440000"``
``email``        Email addresses
``uri``          URLs / hyperlinks
``date``         Calendar dates without a time component
                 (``"2026-12-31"``)
``date-time``    ISO 8601 timestamps
                 (``"2026-12-31T23:59:59Z"``)
``int32``,
``int64``        Numeric identifiers and counters
===============  ===============================================

Where a parameter or response field has a fixed set of legal values,
the spec declares an ``enum`` rather than a free-form string.

Errors
======

Operations declare both successful (``2xx``) and error
(``4xx`` / ``5xx``) responses. Only the codes listed below are ever
returned by the v1 surface; the API does **not** use ``401``,
``409``, ``422`` or ``429``.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Status
     - Meaning
   * - ``400 Bad Request``
     - Malformed input or failed request-shape validation — e.g. a
       missing required parameter or an unparseable body.
   * - ``403 Forbidden``
     - Authentication or authorisation failure. The v1 surface does
       **not** distinguish ``401`` from ``403`` — a missing,
       invalid, or expired token returns ``403`` just like a token
       whose tenant lacks permission for the operation.
   * - ``404 Not Found``
     - The requested resource does not exist or is not visible to
       the authenticated tenant.
   * - ``405`` (repurposed)
     - **Business-rule violation**, not the standard "Method Not
       Allowed". Used for duplicates, password mismatches, invalid
       IBAN/BIC, unsupported parameter combinations and similar
       semantic rejections. Read the ``message`` field for the
       specific cause.
   * - ``406 Not Acceptable``
     - The negotiated response format is not supported for this
       operation.
   * - ``500 Server Error``
     - An unexpected server-side error occurred — safe to retry with
       exponential back-off.

Deprecation
===========

Endpoints scheduled for removal carry ``deprecated: true`` in the
spec. The endpoint's description explains the replacement and, when
one has been agreed, the sunset date. Deprecated endpoints continue
to function until the sunset date.