> For the complete documentation index, see [llms.txt](https://mims.oascities.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mims.oascities.org/accessing-data/mechanisms.md).

# Mechanisms

## Mechanism 1: REST API with JSON Description

#### 1. Overview

This Mechanism defines how public sector data systems can expose data in an interoperable, machine-readable way using **REST APIs described in JSON via OpenAPI 3.1**. It fulfils all capabilities and requirements of MIM1 (Accessing Data) and is grounded in widely adopted open standards from IETF, OGC, and the OpenAPI Initiative.

The Mechanism is intentionally technology-neutral at the payload level: it mandates *how* data is exposed and described, not *what* the data model is (that is the domain of MIM2). It is suitable for a wide range of smart city data — sensor readings, mobility data, environmental monitoring, permit registries, events, and more.

***

#### 2. Core Standards Referenced

| Standard                                                       | Role in this Mechanism                                                                                                      |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **OpenAPI Specification 3.1** (OAI)                            | Formal machine-readable description of all API endpoints, parameters, request/response schemas, content types, and examples |
| **RFC 9110** – HTTP Semantics (IETF)                           | Foundation for all HTTP interactions: methods, status codes, content negotiation via `Accept` / `Content-Type` headers      |
| **RFC 9111** – HTTP Caching (IETF)                             | Cache-Control, ETag, Last-Modified headers for efficient data retrieval                                                     |
| **RFC 7807 / RFC 9457** – Problem Details for HTTP APIs (IETF) | Structured, machine-readable error responses                                                                                |
| **draft-ietf-httpapi-ratelimit-headers** (IETF HTTPAPI WG)     | `RateLimit`, `RateLimit-Policy` headers to communicate quota status to consumers                                            |
| **JSON Schema (2020-12)**                                      | Schema definitions for all request and response payloads, embedded in or referenced from the OpenAPI description            |
| **OGC SensorThings API Part 1** (OGC/ISO 15075-1)              | Recommended profile for IoT/sensor data streams with built-in subscription support via MQTT                                 |
| **OGC API – Features Part 1** (OGC/ISO 19168-1)                | Recommended profile for geospatial feature data with standardised `bbox`, `datetime`, and property filters                  |
| **AsyncAPI 3.0**                                               | Optional complementary description of subscription/notification channels (Webhooks, MQTT, SSE)                              |
| **RFC 8288** – Web Linking (IETF)                              | `Link` headers and hypermedia relations for pagination, self-describing resources                                           |

***

#### 3. Mechanism Description

**3.1 Data Retrieval over HTTP(S)**

All data resources are exposed as **HTTPS endpoints** following RESTful resource-oriented design. Each resource collection is addressable via a stable URI. Clients retrieve data using standard HTTP `GET` requests.

Supported response formats are negotiated using the HTTP `Accept` header (per RFC 9110), with the server indicating the chosen format via `Content-Type`. The Mechanism requires support for at least one machine-readable format; **JSON (`application/json`)** is the baseline, and implementations are encouraged to also support **GeoJSON (`application/geo+json`)**, **JSON-LD (`application/ld+json`)**, and optionally CSV or Parquet for bulk downloads.

Format negotiation can also be achieved via the `?f=` query parameter as a fallback for clients unable to control HTTP headers (following OGC API – Common practice).

**3.2 Formal API Description in JSON**

Every API instance conforming to this Mechanism MUST publish an **OpenAPI 3.1 description document**, accessible at a well-known path (e.g. `/api` or `/openapi.json`). This document:

* Lists all endpoints with their HTTP methods, path parameters, query parameters, and response schemas
* Declares all supported content types per endpoint using the OpenAPI `content` map
* Embeds or references **JSON Schema 2020-12** definitions for all payload structures
* Includes at least one worked example per endpoint (`examples` or `x-` extension fields)
* Documents authentication requirements using OpenAPI `securitySchemes` (see Section 3.5)

The OpenAPI document itself is the machine-readable contract (R1.3) and the payload schema pointer (R1.4).

**3.3 Structured and Queryable Interface**

All collection endpoints follow a uniform URL pattern:

```
GET /collections/{collectionId}/items
```

This pattern is borrowed from **OGC API – Features**, which has been adopted as ISO 19168-1, and ensures structural consistency across implementations from different vendors and cities.

Filtering is performed through standard query parameters, all documented in the OpenAPI description:

| Query Parameter                          | Purpose                                                     | Standard Basis                   |
| ---------------------------------------- | ----------------------------------------------------------- | -------------------------------- |
| `datetime`                               | Filter by time range or instant (`2024-01-01T00:00:00Z/..`) | OGC API – Features               |
| `bbox`                                   | Geospatial bounding box filter                              | OGC API – Features               |
| `properties` (or domain-specific params) | Attribute-level filtering                                   | OGC API – Features Part 3 / CQL2 |
| `limit` / `offset`                       | Pagination                                                  | OGC API – Common                 |
| `f`                                      | Format override                                             | OGC API – Common                 |

Responses include **RFC 8288 `Link` headers** with `rel=next`, `rel=prev`, `rel=self`, and `rel=alternate` to support pagination and format discovery without out-of-band knowledge.

For time-series or sensor data, the **OGC SensorThings API** resource model (Things → Datastreams → Observations) is the recommended profile, with identical query parameter conventions.

**3.4 Subscriptions and Change Notifications**

For use cases requiring near-real-time updates, the Mechanism supports three subscription patterns of increasing complexity:

**Polling (baseline fallback):** Clients repeatedly `GET` a collection endpoint. The API supports `If-None-Match` / `If-Modified-Since` headers (RFC 9111) to enable conditional requests, returning `304 Not Modified` when data has not changed, minimising bandwidth. An `X-Next-Update` header (or equivalent OpenAPI extension) communicates the next expected data refresh time.

**Webhooks:** Clients register a callback URL via a `POST /subscriptions` endpoint described in the OpenAPI document. When data changes, the server issues an HTTP `POST` to the registered URL with a change payload. The subscription resource and callback schema are described using **AsyncAPI 3.0** or as an OpenAPI extension.

**MQTT / SSE (for streaming/IoT):** When using the OGC SensorThings API profile, MQTT publish/subscribe is available as Part 1 already defines the binding. Server-Sent Events (`text/event-stream`) can be offered as a lightweight browser-friendly alternative.

All subscription endpoints and their payload schemas are formally described in the API description document, fulfilling R1.3 for the notification channel.

**3.5 Access Control**

When access restrictions apply, the Mechanism defers to **MIM3** (actor identification) and **MIM6** (authorisation and data asset-level policies). Concretely:

* Actor identification is achieved via **OAuth 2.0 / OpenID Connect** bearer tokens (`Authorization: Bearer …`), declared as an `openIdConnect` or `oauth2` security scheme in the OpenAPI description.
* Authorisation policies (role-based or attribute-based) are enforced at the API gateway or resource server level.
* The OpenAPI description documents which endpoints require which scopes, making the access model machine-readable and auditable.

**3.6 Operational Headers and Best Practices**

Implementations following this Mechanism SHOULD include the following HTTP response headers on all collection endpoints:

| Header                          | Purpose                                                        |
| ------------------------------- | -------------------------------------------------------------- |
| `Cache-Control`                 | Freshness and cacheability (RFC 9111)                          |
| `ETag` / `Last-Modified`        | Conditional request support (RFC 9111)                         |
| `RateLimit`, `RateLimit-Policy` | Quota transparency (IETF draft-ietf-httpapi-ratelimit-headers) |
| `X-Next-Update`                 | Next expected data refresh timestamp                           |
| `Link`                          | Pagination and alternate format links (RFC 8288)               |

Error responses MUST use the **RFC 9457 Problem Details** format (`application/problem+json`), providing `type`, `title`, `status`, `detail`, and optionally `instance` fields. This ensures errors are machine-parseable by generic API clients.

A `GET /health` or `GET /status` endpoint SHOULD be provided, returning a simple structured JSON document indicating service availability, API version, and data freshness.

**3.7 Why This Mechanism Is Interoperable**

This Mechanism achieves interoperability through several complementary layers:

**Syntactic interoperability** is achieved by mandating JSON as the baseline wire format and OpenAPI 3.1 as the formal description language. Any client capable of parsing an OpenAPI document can auto-discover endpoints, parameters, and schemas without prior bilateral agreement.

**Structural interoperability** is achieved through the uniform OGC API – Features / SensorThings resource and query model. A client written for one smart city data portal can query another without reconfiguration, because the endpoint pattern, filtering parameters, and pagination conventions are standardised.

**Semantic interoperability** is supported by the MIM2 data model reference mechanism: the OpenAPI description points to the schema definitions used, which can be JSON-LD contexts or domain ontologies. This Mechanism does not prescribe the model but ensures it is referenceable.

**Protocol interoperability** is guaranteed by grounding everything in IETF HTTP standards (RFC 9110, 9111), which are universally implemented across all languages, platforms, and API gateways.

**Discovery interoperability** is enabled by the well-known OpenAPI document path and the `Link` headers on every response. Aggregators and data catalogues (e.g. DCAT-AP conformant portals) can crawl and index APIs without custom connectors.

***

#### 4. Requirements Mapping Table

| Req. ID                 | Requirement Text                                                                                                                          | How This Mechanism Implements It                                                                                                                                                                                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **R1.1**                | Systems SHALL allow retrieval of data in at least one machine-readable format. Formats can be specified through HTTP Content-Negotiation. | JSON (`application/json`) is the mandatory baseline format. Additional formats (GeoJSON, JSON-LD, CSV) are optionally supported. Format selection uses the HTTP `Accept` header per RFC 9110, or the `?f=` query parameter as a fallback.                                                            |
| **R1.2**                | Data SHALL be retrievable via at least one standard web-based mechanism.                                                                  | Data is retrieved via HTTPS `GET` requests on standard URI-addressed collection endpoints following RESTful conventions and the OGC API – Features URL pattern (ISO 19168-1).                                                                                                                        |
| **R1.3**                | Access mechanism(s) SHALL be formally described.                                                                                          | A machine-readable **OpenAPI 3.1** description document is published at a well-known URL (`/api` or `/openapi.json`). It formally describes all endpoints, methods, parameters, schemas, content types, security, and examples. Subscription channels are additionally described using AsyncAPI 3.0. |
| **R1.4**                | Data Models used by payloads should be specified (see MIM2).                                                                              | The OpenAPI description references JSON Schema 2020-12 definitions for all request and response payloads. These schemas can in turn reference external MIM2-conformant data models via `$ref` or JSON-LD `@context`.                                                                                 |
| **R2.1**                | Systems SHALL provide data through a structured and consistent interface.                                                                 | All collection resources follow the uniform OGC API – Features pattern (`/collections/{id}/items`). Pagination, filtering, and response envelope structures are consistent across all endpoints and documented in the shared OpenAPI description.                                                    |
| **R2.2**                | Systems SHALL support basic querying and/or filtering (e.g. by time, location, attributes).                                               | Filtering is supported via standardised query parameters: `datetime` for temporal filtering, `bbox` for geospatial filtering, and property-level filters (OGC API – Features Part 3 / CQL2). All parameters are documented in the OpenAPI description.                                               |
| **R3.1**                | Systems for use cases that require notifications SHALL provide at least one mechanism to receive updates on data changes.                 | At minimum, polling with conditional HTTP requests (`If-None-Match`, `If-Modified-Since`, `304 Not Modified`) is supported. Implementations with real-time requirements provide Webhooks (POST callbacks) and/or MQTT (via OGC SensorThings API profile).                                            |
| **R3.2**                | Systems MAY support multiple subscription mechanisms depending on use case.                                                               | The Mechanism defines three tiers: (1) conditional polling as a universal baseline, (2) Webhooks for event-driven consumers, and (3) MQTT or Server-Sent Events for streaming/IoT use cases. All are described in the API description document.                                                      |
| **R4 (MIM3/MIM6 ref.)** | Access restrictions SHALL follow MIM3 actor identification and MIM6 authorisation requirements.                                           | OAuth 2.0 / OpenID Connect bearer tokens are used for actor identification. Authorisation scopes are declared in the OpenAPI `securitySchemes` section, making the access policy machine-readable. Data-asset-level policies are enforced at the API gateway level in conformance with MIM6.         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mims.oascities.org/accessing-data/mechanisms.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.