web-server/doc/en/api/1.0.0/coveragestores.yaml

---
swagger: '2.0'
info:
  version: 1.0.0
  title: GeoServer CoverageStores
  description: A coverage store describes how access a raster data source.
  contact:
    name: GeoServer
    email: 'geoserver-users@osgeo.org'
    url: 'https://geoserver.org/comm/'
host: localhost:8080
basePath: /geoserver/rest

paths:
  /workspaces/{workspace}/coveragestores:
    get:
      operationId: getCoverageStores
      tags:
        - "CoverageStores"
      summary: Get a list of all coverage stores in {workspace}
      description: Displays a list of all styles on the server. Use the "Accept:" header to specify format or append an extension to the endpoint (example "/coveragestores.xml" for XML). Defaults to HTML representation.
      produces:
        - text/html
        - application/json
        - application/xml
      parameters:
        - name: workspace
          in: path
          required: true
          description: The name of the workspace containing the coverage stores.
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/CoverageStoreList"
          examples:
            application/json: |
              {
                "coverageStores": {
                  "coverageStore": [
                    {
                      "name": "arcGridSample",
                      "href": "http://localhost:8080/geoserver/restng/workspaces/nurc/coveragestores/arcGridSample.json"
                    },
                    {
                      "name": "worldImageSample",
                      "href": "http://localhost:8080/geoserver/restng/workspaces/nurc/coveragestores/worldImageSample.json"
                    }
                  ]
                }
              }
            
            application/xml: |
              <coverageStores>
                <coverageStore>
                  <name>arcGridSample</name>
                  <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/restng/workspaces/nurc/coveragestores/arcGridSample.xml" type="application/atom+xml"/>
                </coverageStore>
                <coverageStore>
                  <name>worldImageSample</name>
                  <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/restng/workspaces/nurc/coveragestores/worldImageSample.xml" type="application/atom+xml"/>
                </coverageStore>
              </coverageStores>
            
        401:
          description: Unauthorized

    post:
      operationId: postCoverageStores
      tags:
        - "CoverageStores"
      summary: Add a new coverage store
      description: Adds a new coverage store entry to the server.
      parameters:
        - name: workspace
          in: path
          required: true
          description: The name of the workspace containing the coverage stores.
          type: string
        - $ref: "#/parameters/CoverageStorePost"
      consumes:
        - application/xml
        - application/json
      responses:
        201:
          description: Created
          schema:
            type: string
          headers:
            Location:
              description: URL where the newly created store can be found
              type: string
        401:
          description: Unauthorized

    put:
      operationId: putCoverageStores
      tags:
        - "CoverageStores"
      description: Invalid. Use POST for adding a new coverage store, or PUT on /coveragestores/{store} to edit/upload an existing coverage store.
      responses:
        401:
          description: Unauthorized
        405:
          description: Method Not Allowed

    delete:
      operationId: deleteCoverageStores
      tags:
        - "CoverageStores"
      description: Invalid. Use /coverage/{style} instead.
      responses:
        401:
          description: Unauthorized
        405:
          description: Method Not Allowed
  /workspaces/{workspace}/coveragestores/{store}:
    get:
      operationId: getCoverageStore
      tags:
        - "CoverageStores"
      summary: Get a coverage store named {store} in the {workspace} workspace
      description: Displays a representation of the coverage store. Use the "Accept:" header to specify format or append an extension to the endpoint (example "/{store}.xml" for XML). Defaults to HTML representation.
      produces:
        - text/html
        - application/json
        - application/xml
      parameters:
        - name: workspace
          in: path
          required: true
          description: The name of the workspace containing the coverage stores.
          type: string
        - name: store
          in: path
          required: true
          description: The name of the store to be retrieved
          type: string
        - name: quietOnNotFound
          in: query
          required: false
          description: When set to true, avoids logging an Exception when the coverage store is not present. Note that 404 status code will be returned anyway.
          type: boolean
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/CoverageStoreInfo"
          examples:
            application/json: |
              {
                "coverageStore": {
                  "name": "arcGridSample",
                  "description": "Sample ASCII GRID coverage of Global rainfall.",
                  "type": "ArcGrid",
                  "enabled": true,
                  "workspace": {
                    "name": "nurc",
                    "href": "http://localhost:8080/geoserver/restng/workspaces/nurc.json"
                  },
                  "_default": false,
                  "url": "file:coverages/arc_sample/precip30min.asc",
                  "coverages": "http://localhost:8080/geoserver/restng/workspaces/nurc/coveragestores/arcGridSample/coverages.json"
                }
              }
            
            application/xml: |
              <coverageStore>
                <name>arcGridSample</name>
                <description>Sample ASCII GRID coverage of Global rainfall.</description>
                <type>ArcGrid</type>
                <enabled>true</enabled>
                <workspace>
                  <name>nurc</name>
                  <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/restng/workspaces/nurc.xml" type="application/atom+xml"/>
                </workspace>
                <__default>false</__default>
                <url>file:coverages/arc_sample/precip30min.asc</url>
                <coverages>
                  <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/restng/workspaces/nurc/coveragestores/arcGridSample/coverages.xml" type="application/atom+xml"/>
                </coverages>
              </coverageStore>
            
        401:
          description: Unauthorized

    post:
      operationId: postCoverageStore
      tags:
        - "CoverageStores"
      description: Invalid. Use POST on /workspaces/{workspace}/coveragestores for adding a new coverage store, or PUT on /workspaces/{workspace}/coveragestores/{store} to edit/upload an existing coverage store.
      responses:
        401:
          description: Unauthorized
        405:
          description: Method Not Allowed

    put:
      operationId: putCoverageStore
      tags:
        - "CoverageStores"
      summary: Modify a single coverage store.
      description: Modifies a single coverage store. Use the "Accept:" header to specify format or append an extension to the endpoint (example "{store}.xml" for XML).
      parameters:
        - name: workspace
          in: path
          required: true
          description: The name of the workspace containing the coverage stores.
          type: string
        - name: store
          in: path
          required: true
          description: The name of the store to be retrieved
          type: string
        - $ref: "#/parameters/CoverageStorePut"
      consumes:
        - application/xml
        - application/json
      responses:
        200:
          description: The coverage store was successfully updated.
        401:
          description: Unauthorized
          
    delete:
      operationId: deleteCoverageStore
      tags:
        - "CoverageStores"
      summary: Delete coverage store
      description: Deletes a coverage store
      parameters:
        - name: workspace
          in: path
          required: true
          description: The name of the workspace containing the coverage stores.
          type: string
        - name: store
          in: path
          required: true
          description: The name of the store to be retrieved
          type: string
        - name: purge
          in: query
          required: false
          description: The purge parameter specifies if and how the underlying raster data source is deleted. 
                       Allowable values for this parameter are "none", "metadata", "all". 
                       When set to "none" data and auxiliary files are preserved.
                       When set to "metadata" delete only auxiliary files and metadata. It’s recommended when data files (such as granules) should not be deleted from disk.
                       Finally, when set to "all" both data and auxiliary files are removed.
          type: string
        - name: recurse
          in: query
          required: false
          description: The recurse controls recursive deletion. When set to true all resources contained in the store are also removed. The default value is "false".
          type: boolean
      responses:
        200:
          description: OK
        401:
          description: Unauthorized
          
  /workspaces/{workspace}/coveragestores/{store}/{method}.{format}:
    get:
      operationId: getCoverageStoreUpload
      tags:
        - "CoverageStores"
      description: Invalid, only used for uploads
      responses:
        401:
          description: Unauthorized
        405:
          description: Method Not Allowed

    post:
      operationId: postCoverageStoreUpload
      tags:
        - "CoverageStores"
      description: Used to harvest new granules in a writable structured grid coverage reader (e.g., image mosaic). Attempting to harvest a file into any other reader will result in a HTTP 405, method not allowed. Multiple granules can be uploaded by wrapping them in a ZIP file. 
      parameters:
        - name: workspace
          in: path
          required: true
          description: The name of the workspace containing the coverage stores.
          type: string
        - name: store
          in: path
          required: true
          description: The name of the store to be retrieved
          type: string
        - name: method
          in: path
          required: true
          description: The upload method. Can be "url", "file", "external", "remote". 
                       "file" uploads a file from a local source. The body of the request is the file itself.
                       "url" uploads a file from a remote source. The body of the request is a URL pointing to the file to upload. This URL must be visible from the server.
                       "external" uses an existing file on the server. The body of the request is the absolute path to the existing file.
                       "remote" uses a direct reference to a remote url, i.e. a file on a cloud storage. No data copy will occur. The body of the request is a URL pointing to the remote dataset.
          type: string
        - name: format
          in: path
          required: true
          description: The type of target coverage store (e.g., "imagemosaic")
          type: string
        - name: filename
          in: query
          required: false
          description: The filename parameter specifies the target file name for a file that needs to be harvested as part of a mosaic. This is important to avoid clashes and to make sure the right dimension values are available in the name for multidimensional mosaics to work. Only used if method="file".
          type: string
        - name: updateBBox
          in: query
          required: false
          description: When set to "true", triggers re-calculation of the layer native bbox. Defaults to "false".
          type: boolean
      responses:
        200:
          description: The coverage store was successfully updated.
        401:
          description: Unauthorized

    put:
      operationId: putCoverageStoreUpload
      tags:
        - "CoverageStores"
      summary: Creates or overwrites the files for a coverage store
      description: Creates or modified a single coverage store by uploading its raster data files. Multi-file stores like mosaic can be created by uploading a zip file and setting the content type to "application/zip"
      parameters:
        - name: workspace
          in: path
          required: true
          description: The name of the workspace containing the coverage stores.
          type: string
        - name: store
          in: path
          required: true
          description: The name of the store to be retrieved
          type: string
        - name: method
          in: path
          required: true
          description: The upload method. Can be "url", "file", "external", "remote". 
                       "file" uploads a file from a local source. The body of the request is the file itself.
                       "url" uploads a file from a remote source. The body of the request is a URL pointing to the file to upload. This URL must be visible from the server.
                       "external" uses an existing file on the server. The body of the request is the absolute path to the existing file.
                       "remote" uses a direct reference to a remote url, i.e. a file on a cloud storage. No data copy will occur. The body of the request is a URL pointing to the remote dataset.
          type: string
        - name: format
          in: path
          required: true
          description: The type of target coverage store (e.g., "imagemosaic")
          type: string
        - name: configure
          in: query
          required: false
          description: The configure parameter controls if a coverage/layer are configured upon file upload, in addition to creating the store. It can have a value of "none" to avoid configuring coverages.
          type: string
        - name: USE_JAI_IMAGEREAD
          in: query
          required: false
          description: Whether to use deferred loading while configuring the coverage/layer. 
          type: string
        - name: coverageName
          in: query
          required: false
          description: Name of the newly created coverage/layer. 
          type: string
        - name: filename
          in: query
          required: false
          description: The filename parameter specifies the target file name for a file that needs to be harvested as part of a mosaic. This is important to avoid clashes and to make sure the right dimension values are available in the name for multidimensional mosaics to work. Only used if method="file".
          type: string
      responses:
        200:
          description: The coverage store was successfully updated.
        401:
          description: Unauthorized
          
    delete:
      operationId: deleteCoverageStoreUpload
      tags:
        - "CoverageStores"
      description: Invalid, only used for uploads
      responses:
        401:
          description: Unauthorized
        405:
          description: Method Not Allowed

  /workspaces/{workspace}/coveragestores/{store}/reset:
    put:
      operationId: putCoverageStoreReset
      tags:
        - "CoverageStores"
      summary: Reset the caches related to this specific coverage store.
      description: Resets raster caches for this coverage store. This operation is used to force GeoServer to drop caches associated to this coverage store, and reconnect to the raster source the next time it is needed by a request. This is useful as the readers often cache some information about the bounds, coordinate system and image structure that might have changed in the meantime.
      parameters:
        - name: workspace
          in: path
          type: string
          required: true
          description: The name of the workspace containing the coverage store.
        - name: store
          in: path
          required: true
          description: The name of the coverage store to modify.
          type: string      
      responses:
        200:
          description: OK
    post:
      operationId: postCoverageStoreReset
      tags:
        - "CoverageStores"
      summary: Reset the caches related to this specific coverage store.
      description: Resets raster caches for this coverage store. This operation is used to force GeoServer to drop caches associated to this coverage store, and reconnect to the raster source the next time it is needed by a request. This is useful as the readers often cache some information about the bounds, coordinate system and image structure that might have changed in the meantime.
      parameters:
        - name: workspace
          in: path
          type: string
          required: true
          description: The name of the workspace containing the coverage store.
        - name: store
          in: path
          required: true
          description: The name of the coverage store to modify.
          type: string
      responses:
        200:
          description: OK

parameters:
  CoverageStorePost:
    name: coverageStoreBody
    description: |
      The coverage store body information to upload.

      Examples:
      - application/xml:

        ```
        <coverageStore>
          <name>nyc</name>
          <url>file:/path/to/file.tiff</url>
        </coverageStore>
        ```

      - application/json:

        ```
        {
          "coverageStore": {
            "name": "nyc",
            "url": "file:/path/to/file.tiff"
          }
        }
        ```


    in: body
    required: true          
    schema:
      $ref: "#/definitions/CoverageStoreInfo"
  CoverageStorePut:
    name: coverageStoreBody
    description: |
      The coverage store body information to upload.
      For a PUT, only values which should be changed need to be included.

      Examples:
      - application/xml:

        ```
        <coverageStore>
          <description>A coverage store</description>
          <enabled>true</enabled>
          <__default>true</__default>
          <url>file:/path/to/file.tiff</url>
        </coverageStore>
        ```

      - application/json:

        ```
        {
          "coverageStore": {
            "description": "A coverage store",
            "enabled": "true",
            "_default": "true",
            "url": "file:/path/to/file.tiff"
          }
        }
        ```
    in: body
    required: true          
    schema:
      $ref: "#/definitions/CoverageStoreInfo"
          
definitions:
  CoverageStoreInfo:
    type: object
    required: [ name, type ]
    example: |
        <coverageStore>
          <name>arcGridSample</name>
          <description>Sample ASCII GRID coverage of Global rainfall.</description>
          <type>ArcGrid</type>
          <enabled>true</enabled>
          <workspace>
            <name>nurc</name>
            <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/rest/workspaces/nurc.xml" type="application/xml"/>
          </workspace>
          <__default>false</__default>
          <url>file:coverages/arc_sample/precip30min.asc</url>
          <coverages>
            <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/rest/workspaces/nurc/coveragestores/arcGridSample/coverages.xml" type="application/xml"/>
          </coverages>
        </coverageStore>      
        
    properties:
      name:
        type: string
        description: Name of the coverage store
      description:
        type: string
        description: Description of the coverage store
      type:
        type: string
        description: Type of coverage store
      enabled:
        type: boolean
        description: Whether the store is enabled, or not
      workspace:
        type: object
        description: The workspace containing the store
        required: [name]
        properties:
          name: 
            type: string
            description: Name of the workspace
          link:
            type: string
            description: A link to the workspace representation
      __default__:
          type: boolean
          description: Whether the store is the default store of the workspace
      url:
        type: string
        description: Location of the raster data source (often, but not necessarily, a file). Can be relative to the data directory.
      coverages:
        type: object
        properties:
          link:
            type: string
            description: A link to the list of coverages contained in this store
  CoverageStoreListItem:
    type: object
    properties:
      name:
        type: string
        description: Name of coverage store
      href:
        type: string
        description: URL to coverage store definition
  CoverageStoreList:
    type: array
    items:
      $ref: '#/definitions/CoverageStoreListItem'