---
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: |
arcGridSample
worldImageSample
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: |
arcGridSample
Sample ASCII GRID coverage of Global rainfall.
ArcGrid
true
nurc
<__default>false
file:coverages/arc_sample/precip30min.asc
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:
```
nyc
file:/path/to/file.tiff
```
- 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:
```
A coverage store
true
<__default>true
file:/path/to/file.tiff
```
- 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: |
arcGridSample
Sample ASCII GRID coverage of Global rainfall.
ArcGrid
true
nurc
<__default>false
file:coverages/arc_sample/precip30min.asc
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'