API docs by Redocly

Antares operational API (0.1.0)

Download OpenAPI specification:

License: EUPL-1.2

Every route the broker serves outside the NGSI-LD API root (/ngsi-ld/v1), which ETSI GS CIM 009 defines and whose OpenAPI document is vendored beside this one (ngsi-ld-api.yaml).

/q/ is the operator surface: liveness, readiness, Prometheus text, the tenant inventory and purge, and the dead-letter admin. It carries no NGSI-LD semantics and belongs behind the gateway. With ANTARES_ADMIN_TOKEN_FILE set, every /q/ route except health and readiness also asks for that bearer secret (/q/metrics unless ANTARES_ADMIN_METRICS=open); unset, the broker asks for none. A worker pod (ANTARES_ROLES without api) serves these routes and nothing else.

/ex/v1/ is the peer-facing wire between brokers (5.8.1.4), versioned independently of the NGSI-LD API version (ADR-0019).

Deployment surfaces under /x/ document themselves; the broker only guarantees the mount rules.

Errors use the CIM 009 6.3.3 shape: application/json carrying the RFC 7807 members type, title, status, detail.

Health

Liveness, readiness and metrics for the orchestrator and the scraper.

Liveness and the process view

200 with the process view, 503 while the instance drains so a load balancer stops routing before the listener closes. Point the liveness probe here.

Responses

Response samples

Content type
application/json
{
  • "status": "UP",
  • "store": "memory",
  • "temporal": "memory",
  • "storeInfo": {
    },
  • "temporalInfo": {
    },
  • "version": "string",
  • "commit": "string",
  • "notificationSchemes": [
    ],
  • "deadLetters": 0,
  • "changesDropped": 0,
  • "taskPanics": 0,
  • "temporalDrainErrors": 0,
  • "policy": {
    },
  • "surfaces": {
    },
  • "limits": {
    },
  • "memory": {
    },
  • "commitQueueDepth": 0,
  • "commitQueuePeak": 0,
  • "bus": {
    }
}

Readiness for the load balancer

200 when the instance is not draining, the store answers a trivial request (SELECT 1 on Postgres) and, under bus=nats, the bus is connected; 503 otherwise with the failing member false. Point the readiness probe here: a restart does not cure a lost database, so this is not liveness.

Responses

Response samples

Content type
application/json
{
  • "status": "READY",
  • "store": true,
  • "bus": {
    }
}

Prometheus text

Prometheus exposition text with the antares_ prefix. 404 until the broker installs a recorder (ANTARES_TELEMETRY); the metric names are listed in the Admin API chapter of the book.

Authorizations:
NoneadminToken

Responses

Response samples

Content type
application/json
{
  • "type": "urn:antares:error:Unauthorized",
  • "title": "Unauthorized",
  • "status": 401,
  • "detail": "this admin route requires the broker's admin bearer token"
}

Tenants

The customer accounts the backends know. Snapshot tenants and the broker's indexes are internal and never listed.

Tenant names

The names, sorted, and nothing else: at the 10 000-tenant target a list carrying per-kind counts would cost a count per kind per tenant on one request. Pick a name and read its detail.

Authorizations:
NoneadminToken

Responses

Response samples

Content type
application/json
[
  • "default",
  • "acme",
  • "zoo"
]

What one tenant holds

200 with the per-kind counts and bytes, its size. The default tenant always exists (CIM 009 5.5.10) and is readable even when empty. createdAt is present on Postgres, where the tenants table records it. The path names the tenant; an NGSILD-Tenant header is ignored.

Authorizations:
NoneadminToken
path Parameters
tenant
required
string

A tenant name within the tenant grammar; the broker's internal names are refused.

Responses

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "counts": {
    },
  • "bytes": {
    }
}

Tenant purge

Removes every document of the tenant from both backends, snapshots and hosted @context documents included. The default tenant is emptied and keeps existing. Deleted subscriptions and registrations are announced to the bus mirrors the way an API delete is.

Authorizations:
NoneadminToken
path Parameters
tenant
required
string

A tenant name within the tenant grammar; the broker's internal names are refused.

Responses

Response samples

Content type
application/json
{}

Dead letters

Notifications the delivery policy gave up on, kept for one more attempt or for disposal.

Dead letters of one tenant

Newest first. Endpoint userinfo, receiverInfo, notifierInfo and the rendered headers of an older letter are shown blanked; the stored letter keeps them so a replay still authenticates.

Authorizations:
NoneadminToken
query Parameters
tenant
string

The tenant the letters belong to; the default tenant when absent.

subscription
string

Only the letters of this Subscription id.

limit
integer >= 1
Default: 100

Page size, a positive integer up to ANTARES_MAX_LIMIT.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Drop a dead letter

The letter is the only copy of a notification the delivery policy gave up on; this is the one route that discards it.

Authorizations:
NoneadminToken
path Parameters
id
required
string
Examples: urn:ngsi-ld:DeadLetter:6f1c2e7a-8e1b-4c1f-9d3a-2b6a0f5e7c11
query Parameters
tenant
string

The tenant the letters belong to; the default tenant when absent.

Responses

Response samples

Content type
application/json
{}

One more delivery attempt

Re-sends the stored request once through the same binding, under the egress policy of the moment. On success the letter is gone; on failure it is kept with its attempt history extended.

Authorizations:
NoneadminToken
path Parameters
id
required
string
Examples: urn:ngsi-ld:DeadLetter:6f1c2e7a-8e1b-4c1f-9d3a-2b6a0f5e7c11
query Parameters
tenant
string

The tenant the letters belong to; the default tenant when absent.

Responses

Response samples

Content type
application/json
{}

Peer wire

What another broker posts to this one.

Notification from a forwarded subscription copy

Where a Context Source posts a notification for a distributed subscription this broker created (CIM 009 5.8.1.4). The body is an NGSI-LD Notification whose subscriptionId is a broker-generated routing key, never the subscriber's own Subscription id. The NGSILD-Tenant header is not read; the key resolves to the tenant and the local subscription. The body limit and the bounds wall apply as on every route.

Request Body schema: application/json
required
subscriptionId
required
string

The routing key the forwarded copy was created with.

data
Array of objects

The notified Entities; at most ANTARES_MAX_BATCH_ITEMS.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "subscriptionId": "string",
  • "data": [
    ]
}

Response samples

Content type
application/json
{}