web-server/doc/en/api/1.0.0/opensearch-eo.yaml

---
swagger: '2.0'
info:
  version: 1.0.0
  title: OpenSearch for EO search index access
  description: Allows to manipulate the OpenSearch for EO index
  contact:
    name: GeoServer
    email: 'geoserver-users@osgeo.org'
    url: 'https://geoserver.org/comm/'
host: localhost:8080
basePath: /geoserver/rest/oseo/

paths:
  /collections:
    get:
      description: Retrieves a list of all available collections (names and links)
      tags:
       - "OpenSearchEO"
      parameters:
      - name: offset
        in: query
        description: First element for paged responses
        required: false
        type: integer
      - name: limit
        in: query
        description: Number of elements in page
        required: false
        type: integer
      produces:
      - application/json
      responses:
        200:
          description: Success
          examples:
            application/json: |
              {
                "collections" : [
                      {
                        "name" : "SENTINEL1",
                        "href" : "http://host:port/geoserver/rest/oseo/collections/SENTINEL1.json",
                        "search": "http://host:port/geoserver/oseo/description?parentId=SENTINEL1"
                      },
                      {
                        "name" : "SENTINEL2",
                        "href" : "http://host:port/geoserver/rest/oseo/collections/SENTINEL2.json",
                        "search": "http://host:port/geoserver/oseo/description?parentId=SENTINEL2"
                      }
                  ]
              }
    post:
      description: |
        Creates a new collection via its search attributes and ogc links. 
        The zip format accepts a set of files creating the collection in a single shot, and will contain the following files: 
        * collection.json: the list of searchable attributes, the format is the same as the one returned by a GET on a collection, the "*HRef" properties should be omitted. 
        * description.html: the HTML description for the collection
        * metadata.xml: the ISO metadata for the collection
        * thumbnail.png: the collection thumbnail (ignored at the time of writing)
        * owsLinks.json: the list of OWS links, in the same JSON format as the associated resource
        A creation with ZIP is recommend for speed and consistency sake.
      tags:
       - "OpenSearchEO"
      parameters:
      - name: ogc_publish
        in: query
        description: When set to true, instructs GeoServer to automatically publish the collection as a layer in the location GeoServer
        type: boolean
        required: false
      - name: workspace
        in: query
        description: workspace where the collection will be published (if missing the default workspace will be used)
        required: false
        type: string
      - name: layer
        in: query
        description: layer name used when publishing the collection (if missing the collection name will be used)
        type: string
      consumes:
      - application/json
      - application/zip
      responses:
        201:
          description: Created
          headers:
            Location:
              description: The location of the newly created collection
              type: string
        400:
          description: If any error is found in the collection json payload
        409:
          description: Returned if the target collection or layer is already there
  /collections/{collection}:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    get:
      description: Retrieves a collection search attributes and its ogc links
      tags:
       - "OpenSearchEO"
      produces:
      - application/json
      responses:
        200:
          description: Success. The response contains cross links to ogcLinks/metadata/thumbnail sub-resources.
          examples:
            application/json: |
              {
                "type": "Feature",
                "geometry": {
                  "type":"Polygon",
                  "coordinates":[[[-180,-90],[180,-90],[180,90],[-180,90],[-180, -90]]]
                },
                "properties": {
                  "name": "SENTINEL2",
                  "primary": true,
                  "timeStart" : "2012-04-23T18:25:43.511Z",
                  "timeEnd" : null,
                  "queryables" : [ "s2:mean_solar_azimuth", "s2:datastrip_id", "view:sun_azimuth", "sat:anx_datetime", "custom:clouds", "datetime", "eo:cloud_cover" ],
                  "productcqlfilter" : null,
                  "masked" : false,
                  "eo:identifier" : "SENTINEL2",
                  "eo:productType" : "S2MS1C",
                  "eo:platform" : "Sentinel-2",
                  "eo:platformSerialIdentifier" : "A",
                  "eo:instrument" : "MSI",
                  "eo:sensorType" : "OPTICAL",
                  "eo:compositeType" : null,
                  "eo:processingLevel" : "Level-1C",
                  "eo:orbitType" : "LEO",
                  "eo:spectralRange" : null,
                  "eo:wavelength" : null,
                  "eo:securityConstraints" : null,
                  "eo:dissemination" : null,
                  "eo:acquisitionStation" : null,
                  "ogcLinksHref": "http://host:port/geoserver/rest/oseo/collection/SENTINEL2/ogcLinks",
                  "metadataHref": "http://host:port/geoserver/rest/oseo/collection/SENTINEL2/metadata",
                  "thumbnailHref": "http://host:port/geoserver/rest/oseo/collection/SENTINEL2/thumbnail"
                }
              }
        404:
          description: The specified collection cannot be found
    put:
      description: Updates a collection search attributes
      tags:
       - "OpenSearchEO"
      consumes:
      - application/json
      responses:
        200:
          description: Success
        400:
          description: If any error is found in the json payload (details will be provided in the error message)
        404:
          description: The specified collection cannot be found
    delete:
      tags:
       - "OpenSearchEO"
      parameters:
      - name: keepMetadata
        in: query
        description: When present and set to true, makes GeoServer un-publish the collection (removal of OGC links, removal of associated layer) without removing the metadata. The collection remains searchable.
        type: boolean
      description: Deletes a collection and everything inside it
      responses:
        200:
          description: OK
        404:
          description: The specified collection cannot be found

  /collections/{collection}/metadata:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    get:
      description: Returns the ISO metadata of this collection
      tags:
       - "OpenSearchEO"
      produces:
      - application/xml
      responses:
        200:
          description: Success
        404:
          description: The specified collection cannot be found
    put:
      description: Updates/creates a collection ISO metadata
      tags:
       - "OpenSearchEO"
      consumes:
      - application/xml
      responses:
        200:
          description: Success
        400:
          description: The metadata is not a match for the target schema
        404:
          description: The specified collection cannot be found
    delete:
      description: Removes the product metadata
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified collection cannot be found
  /collections/{collection}/ogcLinks:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    get:
      description: Returns the list of OGC links
      tags:
       - "OpenSearchEO"
      produces:
      - text/html
      responses:
        200:
          description: Success
          examples:
            application/json: |
              {
                "links": [
                   {
                     "offering": "http://www.opengis.net/spec/owc/1.0/req/atom/wms",
                     "method": "GET",
                     "code": "GetCapabilities",
                     "type": "application/xml",
                     "href": "${BASE_URL}/sentinel1/ows?service=wms&version=1.3.0&request=GetCapabilities"
                   },
                   {
                     "offering": "http://www.opengis.net/spec/owc/1.0/req/atom/wms",
                     "method": "GET",
                     "code": "GetMap",
                     "type": "image/jpeg",
                     "href": "${BASE_URL}/landsat8/LS8_RGB/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image%2Fjpeg&STYLES&LAYERS=landsat8%3ALS8_RGB&SRS=EPSG%3A4326&WIDTH=800&HEIGHT=600&BBOX=-180%2C-90%2C180%2C90"
                   }
                ]
              }
        404:
          description: The specified collection cannot be found
    put:
      description: Updates/creates a collection OGC links
      tags:
       - "OpenSearchEO"
      consumes:
      - text/html
      responses:
        200:
          description: Success
        400:
          description: The payload does not match the expected structure (
        404:
          description: The specified collection cannot be found
    delete:
      description: Removes the collection OGC links
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified product cannot be found
  /collections/{collection}/thumbnail:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    get:
      description: Returns the thumbnail of this collection
      tags:
       - "OpenSearchEO"
      produces:
      - image/png
      responses:
        200:
          description: Success
        404:
          description: The specified product cannot be found
    put:
      description: Updates/creates a collection thumbnail
      tags:
       - "OpenSearchEO"
      consumes:
      - image/png
      - image/jpeg
      responses:
        200:
          description: Success
        404:
          description: The specified collection cannot be found
    delete:
      description: Removes the collection thumbnail
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified collection cannot be found
  /collections/{collection}/layer:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    get:
      deprecated: true
      description: Returns the current publishing configuration for the layer (or 404 if no configuration is currently in use)
      tags:
       - "OpenSearchEO"
      produces:
      - application/json
      responses:
        200:
          description: Success
          examples:
            application/json: |
              {
                "workspace": "gs",
                "layer": "test123",
                "separateBands": true,
                "bands": [
                      "B02",
                      "B03",
                      "B04",
                      "B08"
                  ],
                  "browseBands": [
                      "B08",
                      "B03",
                      "B02"
                  ],
                "heterogeneousCRS": true,
                "mosaicCRS": "EPSG:4326",
                "defaultLayer": true
              }        
        404:
          description: The specified collection or publishing configuration cannot be found
    put:
      deprecated: true
      description: Removes the previous publshing configuration and replaces with a new one, creating along the mosaic configuration, store, layer and style as described
      tags:
       - "OpenSearchEO"
      consumes:
      - application/json
      responses:
        200:
          description: Success
        400:
          description: The payload does not match the expected structure
        404:
          description: The specified collection cannot be found
    delete:
      deprecated: true
      description: Removes the mosaic configuration, store, layer and style associated to this collection
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified collection or publishing configuration cannot be found
  /collections/{collection}/layers:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    get:
      description: Returns the list of collection layers
      tags:
       - "OpenSearchEO"
      produces:
      - application/json
      responses:
        200:
          description: Success
          examples:
            application/json: |
              {
                "workspace": "gs",
                "layer": "test123",
                "separateBands": true,
                "bands": [
                      "B02",
                      "B03",
                      "B04",
                      "B08"
                  ],
                  "browseBands": [
                      "B08",
                      "B03",
                      "B02"
                  ],
                "heterogeneousCRS": true,
                "mosaicCRS": "EPSG:4326"
              }  
        404:
          description: The specified collection cannot be found
  /collections/{collection}/layers/{layer}:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    - name: layer
      in: path
      description: Identifier of the layer
      required: true
      type: string
    get:
      description: Returns the list of collection layers
      tags:
       - "OpenSearchEO"
      produces:
      - application/json
      responses:
        200:
          description: Success
          examples:
            application/json: |
              {
                "layers": [
                  {
                    "name": "test123-layer1",
                    "href": "http://localhost:8080/geoserver/rest/oseo/collections/TEST123/layers/test123-layer1"
                  },
                  {
                    "name": "test123-layer2",
                    "href": "http://localhost:8080/geoserver/rest/oseo/collections/TEST123/layers/test123-layer2"
                  }
                ]
              }
        404:
          description: The specified collection or layer cannot be found
    put:
      description: Updates/creates a collection layer publishing configuration
      tags:
       - "OpenSearchEO"
      consumes:
      - application/json
      responses:
        200:
          description: Success
        404:
          description: The specified collection cannot be found
    delete:
      description: Removes the collection layer configuration
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified collection or layer cannot be found
  /collections/{collection}/products:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    get:
      description: Returns a paged list of all available products
      tags:
       - "OpenSearchEO"
      parameters:
      - name: offset
        in: query
        description: First element for paged responses
        required: false
        type: integer
        default: 0
      - name: limit
        in: query
        description: Number of elements in page
        required: false
        type: integer
        default: 10
      produces:
      - application/json
      responses:
        200:
          description: Success
          examples:
            application/json: |
              {
                "products" : [
                      {
                        "id" : "S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04",
                        "href" : "http://host:port/geoserver/rest/oseo/collections/SENTINEL2/products/S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04",
                        "rss": "http://host:port/geoserver/oseo/search?uid=S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04"
                      },
                      {
                        "id" : "S2A_OPER_MSI_L1C_TL_SGS__20161207T162012_A007627_T31TCG_N02.04",
                        "href" : "http://host:port/geoserver/rest/oseo/collections/SENTINEL2/products/S2A_OPER_MSI_L1C_TL_SGS__20161207T162012_A007627_T31TCG_N02.04",
                        "rss": "http://host:port/geoserver/oseo/search?uid=S2A_OPER_MSI_L1C_TL_SGS__20161207T162012_A007627_T31TCG_N02.04"
                      }
                ]
              }
        404:
          description: The specified collection cannot be found
    post:
      description: |
        Creates a new product via its search attributes and ogc links. The zip format accepts 
        a set of files creating the collection in a single shot, and will contain the following files: 
        * product.json: the list of searchable attributes and eventual OGC links
        * description.html: the HTML description for the product
        * metadata.xml: the O&M metadata for the collection
        * thumbnail.png: the product thumbnail (can also have jpeg or jpg extension)
        * owsLinks.json: the list of OWS links, in the same JSON format as the associated resource 
        * granules.json: the list of granules, in the same JSON format as the associated resource
        The JSON format is the same as the one returned by a GET on an existing product, the "*Href" properties should be omitted
      tags:
       - "OpenSearchEO"
      consumes:
      - application/json
      - application/zip
      responses:
        201:
          description: Created
          headers:
            Location:
              description: The location of the newly created collection
              type: string
        400:
          description: The payload provided does not match the expected structure (error message will provide details)
        404:
          description: The specified collection cannot be found
        409:
          description: Returned if the target collection or layer is already there
  /collections/{collection}/products/{product}:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    - name: product
      in: path
      description: Identifier of the product
      required: true
      type: string
    get:
      description: |
        Retrieves a product search attributes, ogc links and granules.
        The response contains cross links to ogcLinks/metadata/thumbnail/granules sub-resources, when the same JSON is used to create a new collection the associated can be omitted, or if everything needs to be put in the JSON, the associated representations can be inlined instead (the thumbnail image can be BASE64 encoded). A creation with ZIP is recommend.
      tags:
       - "OpenSearchEO"
      produces:
      - application/json
      - application/xml
      responses:
        200:
          description: Success
          examples:
            application/json: |
              {
                "type": "Feature",
                "geometry": {
                    "type":"Polygon",
                    "coordinates":[[[-180,-90],[180,-90],[180,90],[-180,90],[-180, -90]]]
                },
                "properties": {
                  "eop:identifier" : "S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04",
                  "timeStart" : "2016-09-29T18:59:02Z",
                  "timeEnd" : "2016-09-29T18:59:02Z",
                  "originalPackageLocation" : "/var/data/sentinel2/2017/04/23/S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04.zip",
                  "thumbnailURL" : null,
                  "quicklookURL" : null,
                  "eop:parentIdentifier" : "SENTINEL2",
                  "eop:productionStatus" : null,
                  "eop:acquisitionType" : "NOMINAL",
                  "eop:orbitNumber" : 65,
                  "eop:orbitDirection" : "DESCENDING",
                  "eop:track" : null,
                  "eop:frame" : null,
                  "eop:spwathIdentifier" : null,
                  "opt:cloudCover" : 0,
                  "opt:snowCover" : null,
                  "eop:productQualityStatus" : null,
                  "eop:productQualityDegradationStatus" : null,
                  "eo:processorName" : null,
                  "eop:processingCenter" : null,
                  "eop:creationDate" : "2016-09-29T18:59:02Z",
                  "eop:modificationDate" : null,
                  "eop:processingDate" : null,
                  "eop:sensorMode" : null,
                  "eop:archivingCenter" : "DPA"
                  "eop:processingMode" : "DATA_DRIVEN",
                  "eop:availabilityTime" : null,
                  "eop:acquisitionStation" : null,
                  "eop:acquisitionSubtype" : null,
                  "eop:startTimeFromAscendingNode" : null,
                  "eop:completionTimeFromAscendingNode" : null,
                  "eop:illuminationAzimuthAngle" : null,
                  "eop:illuminationZenithAngle" : null,
                  "eop:illuminationElevationAngle" : null,
                  "sar:polarisationMode" : null,
                  "sar:polarisationChannels" : null,
                  "sar:antennaLookDirection" : null,
                  "sar:minimumIncidenceAngle" : null,
                  "sar:maximumIncidenceAngle" : null,
                  "sar:dopplerFrequency" : null,
                  "sar:incidenceAngleVariation" : null,
                  "eop:resolution" : null,
                  "ogcLinksHref": "http://host:port/geoserver/rest/oseo/collection/SENTINEL2/products/S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04/ogcLinks",
                  "metadataHref": "http://host:port/geoserver/rest/oseo/collection/SENTINEL2/prodcuts/S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04metadata",
                  "thumbnailHref": "http://host:port/geoserver/rest/oseo/collection/SENTINEL2/prodcuts/S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04/thumbnail",
                  "granulesHref": "http://host:port/geoserver/rest/oseo/collection/SENTINEL2/prodcuts/S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04/granules"
                }
              }
        404:
          description: The specified product cannot be found
    put:
      description: Updates a product search attributes and OGC links
      tags:
       - "OpenSearchEO"
      consumes:
      - application/json
      - application/xml
      responses:
        200:
          description: Success
        400:
          description: The payload provided does not match the expected structure (error message will provide details)
        404:
          description: The specified product cannot be found
    delete:
      description: Deletes a product and everything inside it
      tags:
       - "OpenSearchEO"
      parameters:
      - name: keepMetadata
        in: query
        description: When present and set to true, makes GeoServer un-publish the product (removal of OGC links, direct download location and granule references) without removing the metadata. The product remains searchable.
        type: boolean
      responses:
        200:
          description: OK
  /collections/{collection}/products/{product}/metadata:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    - name: product
      in: path
      description: Identifier of the product
      required: true
      type: string
    get:
      description: Returns the O&M metadata of this product
      tags:
       - "OpenSearchEO"
      produces:
      - application/xml
      responses:
        200:
          description: Success
        404:
          description: The specified product cannot be found
    put:
      description: Updates/creates a product O&M metadata
      tags:
       - "OpenSearchEO"
      consumes:
      - application/xml
      responses:
        200:
          description: Success
        400:
          description: The payload provided does not match the expected structure (error message will provide details)
        404:
          description: The specified product cannot be found
    delete:
      description: Removes the product metadata
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified product cannot be found
  /collections/{collection}/products/{product}/thumbnail:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    - name: product
      in: path
      description: Identifier of the product
      required: true
      type: string
    get:
      description: Returns the thumbnail of this product
      tags:
       - "OpenSearchEO"
      produces:
      - image/png
      - image/jpeg
      responses:
        200:
          description: Success
        404:
          description: The specified product cannot be found
    put:
      description: Updates/creates a product thumbnail
      tags:
       - "OpenSearchEO"
      consumes:
      - image/png
      - image/jpeg
      responses:
        200:
          description: Success
        400:
          description: The payload provided does not match the expected structure (error message will provide details)
        404:
          description: The specified product cannot be found
    delete:
      description: Removes the product thumbnail
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified product cannot be found
  /collections/{collection}/products/{product}/ogcLinks:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    - name: product
      in: path
      description: Identifier of the product
      required: true
      type: string
    get:
      description: Returns the list of a product OGC links
      tags:
       - "OpenSearchEO"
      produces:
      - text/html
      responses:
        200:
          description: Success
          examples:
            application/json: |
              [
               {
                 "offering": "http://www.opengis.net/spec/owc/1.0/req/atom/wms",
                 "method": "GET",
                 "code": "GetCapabilities",
                 "type": "application/xml",
                 "href": "${BASE_URL}/sentinel2/S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04/ows?service=wms&version=1.3.0&request=GetCapabilities"
               },
               {
                 "offering": "http://www.opengis.net/spec/owc/1.0/req/atom/wms",
                 "method": "GET",
                 "code": "GetMap",
                 "type": "image/jpeg",
                 "href": "${BASE_URL}/sentinel2/S2A_OPER_MSI_L1C_TL_SGS__20160929T154211_A006640_T32TPP_N02.04/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image%2Fjpeg&STYLES&LAYERS=SENTINEL2-TCI&SRS=EPSG%3A4326&WIDTH=800&HEIGHT=600&BBOX=-180%2C-90%2C180%2C90"
               }
              ]
        404:
          description: The specified collection or product cannot be found
    put:
      description: Updates/creates a products OGC links
      tags:
       - "OpenSearchEO"
      consumes:
      - text/json
      responses:
        200:
          description: Success
        400:
          description: The payload provided does not match the expected structure (error message will provide details)
        404:
          description: The specified collection or product cannot be found
    delete:
      description: Removes the product OGC links
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified collection or product cannot be found
  /collections/{collection}/products/{product}/granules:
    parameters:
    - name: collection
      in: path
      description: Identifier of the collection
      required: true
      type: string
    - name: product
      in: path
      description: Identifier of the product
      required: true
      type: string
    get:
      description: Returns the list of a product granules
      tags:
       - "OpenSearchEO"
      produces:
      - text/json
      responses:
        200:
          description: Success, returns the granules for the given product as a GeoJSON collection
          examples:
            application/json: |
              {
                "type": "FeatureCollection",
                "features": [
                  {
                    "type": "Feature",
                    "geometry": {
                      "type": "Polygon",
                       "coordinate":[[[11.4772,40.5362],[11.5145,41.5243],[10.199,41.5456],[10.1811,40.5567],[11.4772,40.5362]]]
                    },
                    "properties": {
                      "gid": 19,
                      "location": "/efs/geoserver_data/coverages/sentinel/california/S2A_OPER_MSI_L1C_TL_SGS__20160117T141030_A002979_T32TPL_N02.01.tif"
                    },
                    "id": "GRANULE.19"
                  }
                ]
              }
        404:
          description: The specified collection or product cannot be found
    put:
      description: Updates/creates a product granules
      tags:
       - "OpenSearchEO"
      consumes:
      - text/html
      responses:
        200:
          description: Success
        400:
          description: The payload provided does not match the expected structure (error message will provide details)
        404:
          description: The specified collection or product cannot be found
    delete:
      description: Removes the product OGC links
      tags:
       - "OpenSearchEO"
      responses:
        200:
          description: OK
        404:
          description: The specified collection or product cannot be found