API Evangelist enhancements for the SSEN Transmission Open Data Explore API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the SSEN Transmission Open Data Explore API
  version: 1.0.0
extends: openapi/ssen-transmission-opendatasoft-explore-v2.1-openapi.json
x-apievangelist:
  generated: '2026-07-27'
  method: generated
  source: >-
    Generated from the harvested Opendatasoft Explore v2.1 spec plus live probes
    of https://ssentransmission.opendatasoft.com on 2026-07-27. The harvested
    spec is the Opendatasoft platform's, served from SSEN's portal host — it
    carries no SSEN provenance, no rate-limit documentation and no 404 response.
    This overlay records those corrections without mutating the original.
actions:
  - target: $.info
    update:
      x-apievangelist-provider: Scottish and Southern Electricity Networks
      x-apievangelist-provider-id: ssen
      x-apievangelist-business-unit: SSEN Transmission
      x-apievangelist-portal: https://ssentransmission.opendatasoft.com/
      x-apievangelist-corporate-site: https://www.ssen-transmission.co.uk/
      x-apievangelist-spec-authorship: >-
        Platform-vendor spec (Opendatasoft Explore API v2.1) served from the
        SSEN Transmission portal host. Not authored by SSEN. Recorded so it is
        never counted as an SSEN-published API contract.
      x-apievangelist-harvested: '2026-07-27'
      x-apievangelist-harvest-source: https://ssentransmission.opendatasoft.com/api/explore/v2.1/swagger.json
      x-apievangelist-dataset-count: 60
      x-apievangelist-data-licence: CC BY 4.0
      x-apievangelist-access: anonymous read; optional apikey query parameter for private datasets
      x-apievangelist-sector: Electricity transmission (north of Scotland)
      x-apievangelist-regulatory-driver: Ofgem Data Best Practice (Presumed Open, Open Data Triage)

  - target: $.servers
    update:
      - url: https://ssentransmission.opendatasoft.com/api/explore/v2.1
        description: >-
          SSEN Transmission Open Data Portal, Explore API v2.1. Verified HTTP
          200 anonymously on 2026-07-27 (total_count 60).
      - url: https://ssentransmission.opendatasoft.com/api/explore/v2.0
        description: >-
          Prior Explore API version, still answering HTTP 200 on 2026-07-27. Not
          declared in the vendor spec; recorded here because it affects client
          lifecycle planning.

  - target: $.info
    update:
      x-apievangelist-rate-limits:
        observed: '2026-07-27'
        headers: [X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-dataset-Limit, X-RateLimit-dataset-Remaining, X-RateLimit-dataset-Reset]
        anonymous_limit: 100
        window: calendar day (reset is an absolute UTC midnight timestamp)
        artifact: rate-limits/ssen-rate-limits.yml
      x-apievangelist-deprecation-signal:
        header: ODS-Explore-API-Deprecation
        exposed_via: Access-Control-Expose-Headers
        note: >-
          Platform-specific. No RFC 8594 Sunset/Deprecation header, and SSEN
          publishes no deprecation policy.
        artifact: lifecycle/ssen-lifecycle.yml
      x-apievangelist-artifacts:
        authentication: authentication/ssen-authentication.yml
        conventions: conventions/ssen-conventions.yml
        errors: errors/ssen-problem-types.yml
        data_model: data-model/ssen-data-model.yml
        conformance: conformance/ssen-conformance.yml
        lifecycle: lifecycle/ssen-lifecycle.yml
        rate_limits: rate-limits/ssen-rate-limits.yml
        agentic_access: agentic-access/ssen-agentic-access.yml
        mcp: mcp/ssen-mcp.yml
        skills: skills/_index.yml

  - target: $.paths['/catalog/datasets/{dataset_id}/records'].get
    update:
      x-apievangelist-note: >-
        Records are schemaless in this spec (record.additionalProperties is
        open). Call getDataset first and read fields[] to type the rows. Record
        count per call is capped — use the exports endpoints for bulk.
      x-apievangelist-undocumented-response:
        status: 404
        error_code: NotFoundResource
        message_example: The requested dataset zzz-nope does not exist.
        verified: live 2026-07-27
        note: >-
          404 is returned by the live API for an unknown dataset_id but is not
          declared on any operation in the original spec.

  - target: $.paths['/catalog/datasets'].get
    update:
      x-apievangelist-verified:
        status: 200
        date: '2026-07-27'
        total_count: 60
      x-apievangelist-undocumented-response:
        status: 400
        error_code: ODSQLSyntaxError
        message_example: >-
          ODSQL syntax exception: unexpected ( at position 16 in
          invalid_function(). Clause(s) containing the error(s): select.
        verified: live 2026-07-27
        note: >-
          The spec's bad_request example uses error_code ODSQLError; the live
          API also returns ODSQLSyntaxError. Both are real.

  - target: $.paths['/catalog/exports/dcat{dcat_ap_format}'].get
    update:
      x-apievangelist-standard: DCAT
      x-apievangelist-note: >-
        This is the operation that makes the SSEN Transmission catalog
        interoperable with DCAT-AP harvesters. Verified HTTP 200 on 2026-07-27.

  - target: $.components.securitySchemes.apikey
    update:
      x-apievangelist-note: >-
        Optional. All 60 SSEN Transmission datasets are public and read
        anonymously; the key is only needed for private datasets. Passing a key
        in a query string is a weaker posture than a header or Authorization
        bearer — noted, not endorsed.