From f335cc51733a4c61dbfffb35b6398dd4b00f79da Mon Sep 17 00:00:00 2001 From: Josh Fix Date: Tue, 7 Nov 2017 12:37:22 -0500 Subject: [PATCH] refactored features -> items --- spec/spec.yaml | 467 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 467 insertions(+) create mode 100644 spec/spec.yaml diff --git a/spec/spec.yaml b/spec/spec.yaml new file mode 100644 index 000000000..02a3af34a --- /dev/null +++ b/spec/spec.yaml @@ -0,0 +1,467 @@ +swagger: '2.0' +info: + title: A Proposed Imagery Catalog API using the OGC WFS 3.0 standard as a starting point + version: 0.0.3 + description: >- + This document is a proposal draft. Though it is the first one in this folder it is by no means the only one. If others are + contributed they will all be considered equally on Day 1 of the Imagery Catalog API Sprint. This is simply the first one proposed. + If you have additional ideas feel free to either fork this and propose Pull Requests, or create your own new spec-draft and add to this folder. + + + WARNING - THIS IS WORK IN PROGRESS. + + + WARNING - This is a Swagger / OpenAPI 2.0 variant. A final spec should be in OpenAPI 3.0, but this is used for quick code generation purposes. + + contact: + name: Acme Corporation + email: info@example.org + url: 'http://example.org/' + license: + name: CC-BY 4.0 license + url: 'https://creativecommons.org/licenses/by/4.0/' +schemes: + - http +host: data.example.org +basePath: / +paths: + /api: + get: + summary: the API description - this document + operationId: getApiDescription + tags: + - Capabilities + produces: + - application/json + responses: + '200': + description: >- + The formal documentation of this API according to the OpenAPI + specification, version 3.0. I.e., this document. + schema: + type: object + default: + description: An error occured. + schema: + $ref: '#/definitions/exception' + /items: + get: + summary: Retrieve items matching filters + description: >- + Description goes here + operationId: getItems + tags: + - Items + parameters: + - $ref: '#/parameters/bbox' + - $ref: '#/parameters/time' + - $ref: '#/parameters/filter' + - $ref: '#/parameters/limit' + - $ref: '#/parameters/next' + produces: + - application/geo+json + responses: + '200': + description: >- + Description here + schema: + $ref: '#/definitions/ItemCollection' + default: + description: An error occured. + schema: + $ref: '#/definitions/exception' + post: + summary: Retrieve items matching filters + operationId: getItemsPost + tags: + - Items + produces: + - application/geo+json + responses: + '200': + description: >- + Description here + schema: + $ref: '#/definitions/ItemCollection' + default: + description: An error occured. + schema: + $ref: '#/definitions/exception' + '/items/{id}': + get: + summary: Retreive item by id + operationId: getItem + tags: + - Items + parameters: + - $ref: '#/parameters/id' + produces: + - application/geo+json + responses: + '200': + description: An item. + schema: + $ref: '#/definitions/Item' + '404': + description: 'The item with id {id} does not exist.' + schema: + $ref: '#/definitions/exception' + default: + description: An error occured. + schema: + $ref: '#/definitions/exception' +parameters: + next: + name: next + in: query + type: string + description: Token for the next set of paginated data. + limit: + name: limit + in: query + type: integer + description: Defines the maximum number or results retruned by the API + time: + name: time + type: array + description: Adheres to RFC3339 + items: + type: string + in: query + collectionFormat: csv + bbox: + name: bbox + in: query + description: >- + Only items that have a geometry that intersects the bounding box are + selected. The bounding box is provided as four numbers: + + * West, South, East, North + type: array + items: + type: number + minItems: 4 + maxItems: 4 + minimum: -180 + maximum: 180 + collectionFormat: csv + filter: + name: filter + in: query + type: string + description: A placeholder for a future filter implementation + id: + name: id + in: path + description: The id of an item + required: true + type: string +definitions: + exception: + type: object + required: + - code + properties: + code: + type: string + description: + type: string + bbox: + description: >- + West, South, East, North + type: array + items: + minItems: 4 + maxItems: 4 + type: number + minimum: -180 + maximum: 180 + example: + - -180 + - -90 + - 180 + - 90 + link: + type: object + required: + - href + properties: + href: + type: string + rel: + type: string + example: prev + type: + type: string + example: application/geo+json + hreflang: + type: string + example: en + ItemCollection: + type: object + required: + - items + - type + properties: + type: + type: string + enum: + - ItemCollection + items: + type: array + items: + $ref: '#/definitions/Item' + nextPageToken: + type: string + description: A token to obtain the next paginated data set + links: + $ref: '#/definitions/ItemCollectionLinks' + Item: + type: object + required: + - id + - type + - geometry + - links + - properties + properties: + id: + type: string + example: path/to/example.tif + description: 'unique ID, potentially link to file' + bbox: + $ref: '#/definitions/bbox' + geometry: + type: object + description: footprint of the item + type: + type: string + description: The GeoJSON type + enum: + - Item + properties: + $ref: '#/definitions/ItemProperties' + links: + $ref: '#/definitions/ItemLinks' + ItemProperties: + type: object + required: + - start_date + - end_date + description: >- + provides the core metatdata fields plus extensions + properties: + start_date: + $ref: '#/definitions/Time' + end_date: + $ref: '#/definitions/Time' + provider: + type: string + description: Information about the provider + license: + type: string + description: Data license name based on SPDX License List + additionalProperties: + type: object + ItemLinks: + type: object + required: + - self + - thumbnail + properties: + self: + type: string + thumbnail: + type: string + ItemCollectionLinks: + type: object + properties: + next: + type: string + format: url + description: A URL to obtain the next paginated data set. If not present, the client should utilize the `nextPageToken`. + Time: + type: string + description: Adheres to RFC3339 + StringSet: + type: array + items: + type: string + Int64Set: + type: array + items: + type: integer + format: int64 + TimeRange: + description: begin and end timestamps adhering to RFC3339 + properties: + begin: + type: string + end: + type: string + Int64Range: + description: An integer range with begin and end + properties: + begin: + type: integer + format: int64 + end: + type: integer + format: int64 + DoubleRange: + description: A double range with begin and end + properties: + begin: + type: number + format: double + end: + type: number + format: double + Doc: + description: Arbitrary json document + additionalProperties: + type: object + GeoJson: + description: root geojson object + properties: + type: + $ref: '#/definitions/ItemType' + required: + - type + discriminator: type + ItemType: + type: string + enum: + - Point + - MultiPoint + - LineString + - MultiLineString + - Polygon + - MultiPolygon + - GeometryCollection + - Item + - ItemCollection + GeometryCollection: + allOf: + - $ref: '#/definitions/GeoJson' + - type: object + properties: + geometries: + $ref: '#/definitions/GeometryCollection2D' + required: + - geometries + MultiPolygon: + allOf: + - $ref: '#/definitions/GeoJson' + - type: object + properties: + coordinates: + $ref: '#/definitions/MultiPolygon2D' + required: + - coordinates + MultiLineString: + allOf: + - $ref: '#/definitions/GeoJson' + - type: object + properties: + coordinates: + $ref: '#/definitions/MultiLineString2D' + required: + - coordinates + MultiPoint: + allOf: + - $ref: '#/definitions/GeoJson' + - type: object + properties: + coordinates: + $ref: '#/definitions/MultiPoint2D' + required: + - coordinates + Polygon: + allOf: + - $ref: '#/definitions/GeoJson' + - type: object + properties: + coordinates: + $ref: '#/definitions/Polygon2D' + required: + - coordinates + LineString: + allOf: + - $ref: '#/definitions/GeoJson' + - type: object + properties: + coordinates: + $ref: '#/definitions/LineString2D' + required: + - coordinates + Point: + allOf: + - $ref: '#/definitions/GeoJson' + - type: object + properties: + coordinates: + $ref: '#/definitions/Point2D' + required: + - coordinates + GeoPolygon2D: + description: A geojson 2d polygon + type: object + properties: + type: + description: Type of geometry + type: string + enum: + - Polygon + coordinates: + $ref: '#/definitions/Polygon2D' + required: + - type + - coordinates + GeometryCollection2D: + type: array + items: + $ref: '#/definitions/GeoJson' + MultiPolygon2D: + type: array + items: + $ref: '#/definitions/Polygon2D' + Polygon2D: + type: array + minItems: 1 + items: + $ref: '#/definitions/LinearRing2D' + MultiLineString2D: + type: array + items: + $ref: '#/definitions/LineString2D' + LinearRing2D: + type: array + minItems: 4 + items: + $ref: '#/definitions/Point2D' + LineString2D: + type: array + minItems: 2 + items: + $ref: '#/definitions/Point2D' + MultiPoint2D: + type: array + minItems: 2 + items: + $ref: '#/definitions/Point2D' + Point2D: + description: A 2d geojson point + type: array + minimum: 2 + maximum: 2 + items: + type: number + format: double +tags: + - name: Capabilities + description: >- + Essential characteristics of this API including information about the + data. + - name: Items + description: Access to data (items).