overlay: 1.0.0 info: title: API Evangelist enhancements — Near Space Labs Tile Service version: 1.0.0 extends: ../openapi/near-space-labs-tile-service.json x-provenance: generated: '2026-08-26' method: generated source: >- Enhancements API Evangelist would apply to the provider's own Swagger 2.0 contract fetched verbatim from https://api.nearspacelabs.net/tile/openapi/tile-server on 2026-08-26. The original is never mutated. Every value below is taken from the provider's own documentation (docs.nearspacelabs.com) or from the contract itself — nothing is invented. x-gaps-addressed: - The document declares no `host`, `basePath` or `schemes`, so no client can resolve a request URL from it. The real base is https://api.nearspacelabs.net, documented on every docs page and used throughout the provider's own Postman collection. - No operation declares an `operationId`, so no generator can name a method and no Agent Skill or MCP tool can reference an operation by identifier. - No operation declares `tags`, so the 19 paths render as one flat list. - No `securityDefinitions` and no `security` block, even though the sibling OAuth Service contract states "Authentication is required for all endpoints" and every operation here declares 401 and 403 responses. A generator reading this file alone emits an unauthenticated client. - Nine legacy un-versioned /tile/ operations are described as deprecated in the docs and grouped in a "deprecated" folder in the provider's Postman collection, but none carries `deprecated: true`. - 429 (rate limit) and 422 (unprocessable) are documented on docs.nearspacelabs.com/error-handling but declared on no operation. - The `basemap` reserved survey id is documented in prose only and appears nowhere in the contract. actions: - target: $ description: Declare the production host and scheme so the contract is resolvable. update: host: api.nearspacelabs.net schemes: - https - target: $ description: >- Declare the two credential shapes the provider documents at https://docs.nearspacelabs.com/authentication and apply them globally. update: securityDefinitions: oauth2ClientCredentials: type: oauth2 flow: application tokenUrl: https://api.nearspacelabs.net/oauth/token scopes: {} description: >- OAuth 2.0 client credentials. POST client_id, client_secret, audience (https://api.nearspacelabs.com) and grant_type=client_credentials to /oauth/token; present the returned JWT as `Authorization: Bearer `. Tokens are valid for 60 minutes. staticApiKey: type: apiKey in: query name: api_key description: >- A one-year static JWT issued by POST /oauth/static_key, passed as ?api_key=. Carries the same permissions as an OAuth token. The provider warns it "travels in the URL, where it can end up in server logs and browser history". security: - oauth2ClientCredentials: [] - staticApiKey: [] - target: $ description: Declare tag groups so the surface is navigable. update: tags: - name: Surveys description: Catalog operations — list surveys, find surveys by area, fetch footprints. - name: Coverage description: Tile-level metadata for an area of interest, including static tile URLs. - name: Tiles description: XYZ tile delivery, 256x256 PNG/JPEG, zoom 14-21. - name: Deprecated description: Legacy un-versioned /tile/ routes retained for compatibility; use /tile/v2/. - target: $.paths['/tile/v2/surveys'].get description: Name and classify the paginated survey catalog operation. update: operationId: listSurveys tags: [Surveys] - target: $.paths['/tile/v2/surveys/coverage'].get description: Name and classify the area-of-interest survey search. update: operationId: findSurveysByArea tags: [Surveys] - target: $.paths['/tile/v2/{mosaic_id}/footprint'].get description: Name and classify the survey footprint operation. update: operationId: getSurveyFootprint tags: [Surveys] - target: $.paths['/tile/v2/{mosaic_id}/coverage'].get description: Name and classify the per-survey coverage operation. update: operationId: getSurveyCoverage tags: [Coverage] - target: $.paths['/tile/v2/{mosaic_id}/mosaic_updates'].get description: Name and classify the change-detection feed. update: operationId: listMosaicUpdates tags: [Coverage] - target: $.paths['/tile/v2/{mosaic_id}/{z}/{x}/{y}'].get description: Name and classify the latest-mosaic tile operation. update: operationId: getLatestTile tags: [Tiles] - target: $.paths['/tile/v2/{mosaic_id}/{z}/{x}/{y}.{ext}'].get description: Name and classify the latest-mosaic tile operation with an explicit format. update: operationId: getLatestTileWithExtension tags: [Tiles] - target: $.paths['/tile/v2/{mosaic_id}/{mosaic_stac_id}/{z}/{x}/{y}'].get description: Name and classify the historical-capture tile operation. update: operationId: getHistoricalTile tags: [Tiles] - target: $.paths['/tile/v2/{mosaic_id}/{mosaic_stac_id}/{z}/{x}/{y}.{ext}'].get description: Name and classify the historical-capture tile operation with an explicit format. update: operationId: getHistoricalTileWithExtension tags: [Tiles] - target: $.paths['/tile/rsm/{z}/{x}/{y}.{ext}'].get description: Name and classify the RSM mosaic tile operation. update: operationId: getRsmTile tags: [Tiles] - target: $.paths['/tile/surveys'].get description: Mark the legacy survey list deprecated, per the docs and the provider's Postman collection. update: operationId: listSurveysLegacy tags: [Deprecated] deprecated: true - target: $.paths['/tile/surveys/coverage'].get description: Mark the legacy area search deprecated. update: operationId: findSurveysByAreaLegacy tags: [Deprecated] deprecated: true - target: $.paths['/tile/{mosaic_id}/coverage'].get description: Mark the legacy coverage operation deprecated. update: operationId: getSurveyCoverageLegacy tags: [Deprecated] deprecated: true - target: $.paths['/tile/{mosaic_id}/footprint'].get description: Mark the legacy footprint operation deprecated. update: operationId: getSurveyFootprintLegacy tags: [Deprecated] deprecated: true - target: $.paths['/tile/{mosaic_id}/mosaic_updates'].get description: Mark the legacy mosaic-updates operation deprecated. update: operationId: listMosaicUpdatesLegacy tags: [Deprecated] deprecated: true - target: $.paths['/tile/{mosaic_id}/{z}/{x}/{y}'].get description: Mark the legacy latest-tile operation deprecated. update: operationId: getLatestTileLegacy tags: [Deprecated] deprecated: true - target: $.paths['/tile/{mosaic_id}/{z}/{x}/{y}.{ext}'].get description: Mark the legacy latest-tile-with-extension operation deprecated. update: operationId: getLatestTileWithExtensionLegacy tags: [Deprecated] deprecated: true - target: $.paths['/tile/{mosaic_id}/{mosaic_stac_id}/{z}/{x}/{y}'].get description: Mark the legacy historical-tile operation deprecated. update: operationId: getHistoricalTileLegacy tags: [Deprecated] deprecated: true - target: $.paths['/tile/{mosaic_id}/{mosaic_stac_id}/{z}/{x}/{y}.{ext}'].get description: Mark the legacy historical-tile-with-extension operation deprecated. update: operationId: getHistoricalTileWithExtensionLegacy tags: [Deprecated] deprecated: true x-recommended-but-not-applied: - >- Declare the 429 and 422 responses the docs publish, with the shared error envelope {error, message, status_code, x-correlation-id}. Not applied as an overlay action because it would require authoring response schemas the provider has not published per-operation. - >- Hoist the repeated inline Survey / CoverageItem / Footprint shapes into `definitions` and $ref them. The contract currently re-inlines Survey with a different field set on each of the three operations that return it. See data-model/near-space-labs-data-model.yml. - >- Document the reserved `basemap` survey id, either as an enum value on `mosaic_id` or as its own path. It is currently prose-only on docs.nearspacelabs.com/retrieving-tiles. - >- Publish the contract as OpenAPI 3.1 rather than Swagger 2.0, which would allow binary tile responses and the JSON metadata projection of the same path to be described side by side.