REST Configuration API Reference¶
Formats and representations¶
A format specifies how a resource should be represented. A format is used:
- In an operation to specify what representation should be returned to the client
- In a POST or PUT operation to specify the representation being sent to the server
In a GET operation the format can be specified in a number of ways. The first is with the Accepts header. For instance setting the header to “text/xml” would specify the desire to have the resource returned as XML. The second method of specifying the format is via file extension. For example consider the resource “foo”. To request a representation of foo as XML the request uri would end with “foo.xml”. To request as JSON the request uri would end with “foo.json”. When no format is specified the server will use its own internal format, usually html.
In a POST or PUT operation the format specifies 1) the representatin of the content being sent to the server, and 2) the representation of the resposne to be sent back. The former is specified with the Content-type header. To send a representation in XML, the content type “text/xml” or “application/xml” would be used. The latter is specified with the Accepts header as specified in the above paragraph describing a GET operation.
The following table defines the Content-type values for each format:
| Format | Content-type |
|---|---|
| XML | application/xml |
| JSON | application/json |
| HTML | application/html |
| SLD | application/vnd.ogc.sld+xml |
Authentication¶
POST, PUT, and DELETE requests (requests that modify resources) require the client to be authenticated. Currently the only supported method of authentication is Basic authentication. See the examples section for examples of how to perform authentication with various clients and environments.
Status codes¶
A Http request uses a status code to relay the outcome of the request to the client. Different status codes are used for various purposes through out this document. These codes are described in detail by the http specification.
Workspaces¶
A workspace is a grouping of data stores. More commonly known as a namespace, it is commonly used to group data that is related in some way.
Note
For GeoServer 1.x a workspace can be considered the equivalent of a namespace, and the two are kept in sync. For example, the namespace “topp, http://openplans.org/topp” corresponds to the workspace “topp”.
Operations¶
/workspaces[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | List all workspaces | 200 | HTML, XML, JSON | HTML |
| POST | Create a new workspace | 201 with Location header | XML, JSON | |
| PUT | 405 | |||
| DELETE | 405 |
Representations:
/workspaces/<ws>[.<format>]
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Returns workspace ws | 200 | HTML, XML, JSON | HTML | |
| POST | 405 | ||||
| PUT | 200 | Modify workspace ws | XML, JSON | ||
| DELETE | 200 | Delete workspace ws | XML, JSON | recurse |
Representations:
Exceptions:
- GET for a workspace that does not exist -> 404
- PUT that changes name of workspace -> 403
- DELETE against a workspace that is non-empty -> 403
The recurse parameter is used to recursively delete all resources contained by the specified workspace. This includes data stores, coverage stores, feature types, etc... Allowable values for this parameter are “true” or “false”. The default value is “false”.
/workspaces/default[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | Returns default workspace | 200 | HTML, XML, JSON | HTML |
| POST | 405 | |||
| PUT | 200 | Set default workspace | XML, JSON | |
| DELETE | 405 |
Namespaces¶
A namespace is a uniquely identifiable grouping of feature types. A namespaces is identified by a prefix and a uri.
Note
In GeoServer 1.7.x a namespace is used to group data stores, serving the same purpose as a workspace. In 1.7.x the two are kept in sync. Therefore when adding a new namespace a workspace whose name matches the prefix of the namespace is implicitly created.
Operations¶
/namespaces[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | List all namespaces | 200 | HTML, XML, JSON | HTML |
| POST | Create a new namespace | 201 with Location header | XML, JSON | |
| PUT | 405 | |||
| DELETE | 405 |
Representations:
/namespaces/<ns>[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | Returns namespace ns | 200 | HTML, XML, JSON | HTML |
| POST | 405 | |||
| PUT | 200 | Modify namespace ns | XML, JSON | |
| DELETE | 200 | Delete namespace ns | XML, JSON |
Representations:
Exceptions:
- GET for a namespace that does not exist -> 404
- PUT that changes prefix of namespace -> 403
- DELETE against a namespace whose corresponding workspace is non-empty -> 403
/namespaces/default[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | Returns default namespace | 200 | HTML, XML, JSON | HTML |
| POST | 405 | |||
| PUT | 200 | Set default namespace | XML, JSON | |
| DELETE | 405 |
Data stores¶
A data store is a source of spatial data that is vector based. It can be a file in the case of a Shapefile, a database in the case of PostGIS, or a server in the case of a remote Web Feature Service.
Operations¶
/workspaces/<ws>/datastores[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | List all data stores in workspace ws | 200 | HTML, XML, JSON | HTML |
| POST | Create a new data store | 201 with Location header | XML, JSON | |
| PUT | 405 | |||
| DELETE | 405 |
Representations:
/workspaces/<ws>/datastores/<ds>[.<format>]
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Return data store ds | 200 | HTML, XML, JSON | HTML | |
| POST | 405 | ||||
| PUT | Modify data store ds | ||||
| DELETE | Delete data store ds | recurse |
Representations:
Exceptions:
- GET for a data store that does not exist -> 404
- PUT that changes name of data store -> 403
- PUT that changes workspace of data store -> 403
- DELETE against a data store that contains configured feature types -> 403
The recurse parameter is used to recursively delete all feature types contained by the specified data store. Allowable values for this parameter are “true” or “false”. The default value is “false”.
/workspaces/<ws>/datastores/<ds>/file[.<extension>] /workspaces/<ws>/datastores/<ds>/url[.<extension>] /workspaces/<ws>/datastores/<ds>/external[.<extension>]
This operation uploads a file containing spatial data into an existing datastore, or creates a new datastore.
The extension parameter specifies the type of data being uploaded. The following extensions are supported:
| Extension | Datastore |
|---|---|
| shp | Shapefile |
| properties | Property file |
| h2 | H2 Database |
| spatialite | SpatiaLite Database |
The file, url, and external endpoints are used to specify the method that is used to upload the file.
The file method is used to directly upload a file from a local source. The body of the request is the file itself.
The url method is used to indirectly upload a file from an remote source. The body of the request is a url pointing to the file to upload. This url must be visible from the server.
The external method is used to forgo upload and use an existing file on the server. The body of the request is the absolute path to the existing file.
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Get the underlying files for the data store as a zip file with mime type application/zip. Deprecated. | 200 | |||
| POST | 405 | ||||
| PUT | Uploads files to the data store ds, creating it if necessary. | 200 | See notes below. | configure, target, update | |
| DELETE | 405 |
Exceptions:
- GET for a data store that does not exist -> 404
- GET for a data store that is not file based -> 404
When the file for a datastore are PUT, it can be as a standalone file, or as a zipped archive. The standalone file method is only applicable to data stores that work from a single file, GML for example. Data stores like Shapefile must be sent as a zip archive.
When uploading a zip archive the Content-type should be set to application/zip. When uploading a standalone file the content type should be appropriately set based on the file type.
The configure parameter is used to control how the data store is configured upon file upload. It can take one of the three values “first”, “none”, or “all”.
- first - Only setup the first feature type available in the data store. This is the default.
- none - Do not configure any feature types.
- all - Configure all feature types.
The target parameter is used to control the type of datastore that is created on the server when the datastore being PUT to does not exist. The allowable values for this parameter are the same as for the extension parameter.
The update parameter is used to control how existing data is handled when the file is PUT into a datastore that (a) already exists and (b) already contains a schema that matches the content of the file. It can take one of the two values “append”, or “overwrite”.
- append - Data being uploaded is appended to the existing data. This is the default.
- overwrite - Data being uploaded replaces any existing data.
Feature types¶
A feature type is a vector based spatial resource or data set that originates from a data store. In some cases, like Shapefile, a feature type has a one-to-one relationship with its data store. In other cases, like PostGIS, the relationship of feature type to data store is many-to-one, with each feature type corresponding to a table in the database.
Operations¶
/workspaces/<ws>/datastores/<ds>/featuretypes[.<format>]
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | List all feature types in datastore ds | 200 | HTML, XML, JSON | HTML | list |
| POST | Create a new feature type, see notes below | 201 with Location header | XML, JSON | ||
| PUT | 405 | ||||
| DELETE | 405 |
Representations:
Exceptions:
- GET for a feature type that does not exist -> 404
- PUT that changes name of feature type -> 403
- PUT that changes data store of feature type -> 403
When creating a new feature type via POST, if no underlying dataset with the specified name exists an attempt will be made to create it. This will work only in cases where the underlying data format supports the creation of new types (such as a database). When creating a feature type in this manner the client should include all attribute information in the feature type representation.
The list parameter is used to control the category of feature types that are returned. It can take one of the three values “configured”, “available”, or “all”.
- configured - Only setup or configured feature types are returned. This is the default value.
- available - Only unconfigured feature types (not yet setup) but are available from the specified datastore will be returned.
- available_with_geom - Same as available but only includes feature types that have a geometry attribute.
- all - The union of configured and available.
/workspaces/<ws>/datastores/<ds>/featuretypes/<ft>[.<format>]
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Return feature type ft | 200 | HTML, XML, JSON | HTML | |
| POST | 405 | ||||
| PUT | Modify feature type ft | 200 | XML,JSON | ||
| DELETE | Delete feature type ft | 200 | recurse |
Representations:
Exceptions:
- GET for a feature type that does not exist -> 404
- PUT that changes name of feature type -> 403
- PUT that changes data store of feature type -> 403
The recurse parameter is used to recursively delete all layers that reference by the specified feature type. Allowable values for this parameter are “true” or “false”. The default value is “false”.
Coverage stores¶
A coverage store is a source of spatial data that is raster based.
Operations¶
/workspaces/<ws>/coveragestores[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | List all coverage stores in workspace ws | 200 | HTML, XML, JSON | HTML |
| POST | Create a new coverage store | 201 with Location header | XML, JSON | |
| PUT | 405 | |||
| DELETE | 405 |
Representations:
/workspaces/<ws>/coveragestores/<cs>[.<format>]
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Return coverage store cs | 200 | HTML, XML, JSON | HTML | |
| POST | 405 | ||||
| PUT | Modify coverage store cs | ||||
| DELETE | Delete coverage store ds | recurse |
Representations:
Exceptions:
- GET for a coverage store that does not exist -> 404
- PUT that changes name of coverage store -> 403
- PUT that changes workspace of coverage store -> 403
- DELETE against a coverage store that contains configured coverage -> 403
The recurse parameter is used to recursively delete all coverages contained by the specified coverage store. Allowable values for this parameter are “true” or “false”. The default value is “false”.
/workspaces/<ws>/coveragestores/<cs>/file[.<extension>]
The extension parameter specifies the type of coverage store. The following extensions are supported:
| Extension | Coveragestore |
|---|---|
| geotiff | GeoTIFF |
| worldimage | Geo referenced image (JPEG,PNG,TIF) |
| imagemosaic | Image mosaic |
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Get the underlying files for the coverage store as a zip file with mime type application/zip. | 200 | |||
| POST | 405 | ||||
| PUT | Creates or overwrites the files for coverage store cs. | 200 | See notes below. | configure, coverageName | |
| DELETE | 405 |
Exceptions:
- GET for a data store that does not exist -> 404
- GET for a data store that is not file based -> 404
When the file for a coveragestore is PUT, it can be as a standalone file, or as a zipped archive. The standalone file method is only applicable to coverage stores that work from a single file, GeoTIFF for example. Coverage stores like Image moscaic must be sent as a zip archive.
When uploading a zip archive the Content-type should be set to application/zip. When uploading a standalone file the content type should be appropriately set based on the file type.
The coverageName parameter is used to specify the name of the coverage within the coverage store. This parameter is only relevant if the configure parameter is not equal to “none”. If not specified the resulting coverage will receive the same name as its containing coverage store.
Note
Currently the relationship between a coverage store and a coverage is one to one. However there is currently work underway to support multi-dimensional coverages, so in the future this parameter is likely to change.
Coverages¶
A coverage is a raster based data set which originates from a coverage store.
Operations¶
/workspaces/<ws>/coveragestores/<cs>/coverages[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | List all coverages in coverage store cs | 200 | HTML, XML, JSON | HTML |
| POST | Create a new coverage | 201 with Location header | XML, JSON | |
| PUT | 405 | |||
| DELETE | 405 |
Representations:
/workspaces/<ws>/coveragestores/<cs>/coverages/<c>[.<format>]
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Return coverage c | 200 | HTML, XML, JSON | HTML | |
| POST | 405 | ||||
| PUT | Modify coverage c | 200 | XML,JSON | ||
| DELETE | Delete coverage c | 200 | recurse |
Representations:
Exceptions:
- GET for a coverage that does not exist -> 404
- PUT that changes name of coverage -> 403
- PUT that changes coverage store of coverage -> 403
The recurse parameter is used to recursively delete all layers that reference by the specified coverage. Allowable values for this parameter are “true” or “false”. The default value is “false”.
Styles¶
A style describes how a resource (feature type or coverage) should be symbolized or rendered by a Web Map Service. In GeoServer styles are specified with SLD.
Operations¶
/styles[.<format>]
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Return all styles | 200 | HTML, XML, JSON | HTML | |
| POST | Create a new style | 201 with Location header | SLD, XML, JSON See notes below | name | |
| PUT | 405 | ||||
| DELETE | 405 | purge |
Representations:
When POSTing or PUTing a style as SLD, the Content-type header should be set to application/vnd.ogc.sld+xml.
The name parameter specifies the name to be given to the style. This option is most useful when POSTing a style in SLD format, and an appropriate name can be not be inferred from the SLD itself.
/styles/<s>[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | Return style s | 200 | SLD, HTML, XML, JSON | HTML |
| POST | 405 | |||
| PUT | Modify style s | 200 | SLD, XML, JSON See notes above | |
| DELETE | Delete style s | 200 |
The purge parameter specifies whether the underlying SLD file for the style should be deleted on disk. It is specified as a boolean value (true|false). When set to true the underlying file will be deleted.
Representations:
Exceptions:
- GET for a style that does not exist -> 404
- PUT that changes name of style -> 403
- DELETE against style which is referenced by existing layers -> 403
Layers¶
A layer is a published resource (feature type or coverage).
Note
In GeoServer 1.x a layer can considered the equivalent of a feature type or a coverage. In GeoServer 2.x, the two will be separate entities, with the relationship from a feature type to a layer being one-to-many.
Operations¶
/layers[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | Return all layers | 200 | HTML, XML, JSON | HTML |
| POST | 405 | |||
| PUT | 405 | |||
| DELETE | 405 |
Representations:
/layers/<l>[.<format>]
| Method | Action | Return Code | Formats | Default Format | Parameters |
|---|---|---|---|---|---|
| GET | Return layer l | 200 | HTML, XML, JSON | HTML | |
| POST | 405 | ||||
| PUT | Modify layer l | 200 | XML,JSON | ||
| DELETE | Delete layer l | 200 | recurse |
Representations:
Exceptions:
- GET for a layer that does not exist -> 404
- PUT that changes name of layer -> 403
- PUT that changes resource of layer -> 403
The recurse parameter is used to recursively delete all resources referenced by the specified layer. Allowable values for this parameter are “true” or “false”. The default value is “false”.
/layers/<l>/styles[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | Return all styles for layer l | 200 | SLD, HTML, XML, JSON | HTML |
| POST | Add a new style to layer l | 201, with Location header | XML, JSON | |
| PUT | 405 | |||
| DELETE | 405 |
Layer groups¶
A layer group is a grouping of layers and styles that can be accessed as a single layer in a WMS GetMap request. A Layer group is often referred to as a “base map”.
Operations¶
/layergroups[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | Return all layer groups | 200 | HTML, XML, JSON | HTML |
| POST | Add a new layer group | 201, with Location header | XML,JSON | |
| PUT | 405 | |||
| DELETE | 405 |
Representations:
/layergroups/<lg>[.<format>]
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | Return layer group lg | 200 | HTML, XML, JSON | HTML |
| POST | 405 | |||
| PUT | Modify layer group lg | 200 | XML,JSON | |
| DELETE | Delete layer group lg | 200 |
Representations:
Exceptions:
- GET for a layer group that does not exist -> 404
- POST that specifies layer group with no layers -> 400
- PUT that changes name of layer group -> 403
Configuration reloading¶
Reloads the catalog and configuration from disk. This operation is used to reload GeoServer in cases where an external tool has modified the on disk configuration. This operation will also force GeoServer to drop any internal caches and reconnect to all data stores.
/reload
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | 405 | |||
| POST | Reloads the configuration from disk | 200 | ||
| PUT | Reloads the configuration from disk | 200 | ||
| DELETE | 405 |
Resource reset¶
Resets all store/raster/schema caches and starts fresh. This operation is used to force GeoServer to drop all caches and stores and reconnect fresh to each of them first time they are needed by a request. This is useful in case the stores themselves cache some information about the data structures they manage that changed in the meantime.
/reset
| Method | Action | Return Code | Formats | Default Format |
|---|---|---|---|---|
| GET | 405 | |||
| POST | Reloads the configuration from disk | 200 | ||
| PUT | Reloads the configuration from disk | 200 | ||
| DELETE | 405 |