.. _rest_config_api_ref: 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: .. list-table:: :header-rows: 1 * - 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 :ref:`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[.]`` .. list-table:: :header-rows: 1 * - 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*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` ``/workspaces/[.]`` .. list-table:: :header-rows: 1 * - 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 - - :ref:`recurse ` *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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 .. _workspace_recurse: 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[.]`` .. list-table:: :header-rows: 1 * - 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[.]`` .. list-table:: :header-rows: 1 * - 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*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` ``/namespaces/[.]`` .. list-table:: :header-rows: 1 * - 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*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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[.]`` .. list-table:: :header-rows: 1 * - 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//datastores[.]`` .. list-table:: :header-rows: 1 * - 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*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` ``/workspaces//datastores/[.]`` .. list-table:: :header-rows: 1 * - 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`` - - - - :ref:`recurse ` *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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 .. _datastore_recurse: 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//datastores//file[.]`` ``/workspaces//datastores//url[.]`` ``/workspaces//datastores//external[.]`` This operation uploads a file containing spatial data into an existing datastore, or creates a new datastore. .. _extension_parameter: The ``extension`` parameter specifies the type of data being uploaded. The following extensions are supported: .. list-table:: :header-rows: 1 * - 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. .. list-table:: :header-rows: 1 * - 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 :ref:`notes ` below. - - :ref:`configure `, :ref:`target `, :ref:`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 .. _datastore_file_put_notes: 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. .. _configure_parameter: 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. .. _target_parameter: 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 :ref:`extension parameter `. .. _update_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//datastores//featuretypes[.]`` .. list-table:: :header-rows: 1 * - Method - Action - Return Code - Formats - Default Format - Parameters * - GET - List all feature types in datastore ``ds`` - 200 - HTML, XML, JSON - HTML - :ref:`list ` * - POST - Create a new feature type, see :ref:`notes ` below - 201 with ``Location`` header - XML, JSON - - * - PUT - - 405 - - - * - DELETE - - 405 - - - *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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 .. _featuretypes_post_notes: 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. .. _list_parameter: 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//datastores//featuretypes/[.]`` .. list-table:: :header-rows: 1 * - 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 - - - :ref:`recurse ` *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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 .. _featuretype_recurse: 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//coveragestores[.]`` .. list-table:: :header-rows: 1 * - 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*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` ``/workspaces//coveragestores/[.]`` .. list-table:: :header-rows: 1 * - 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`` - - - - :ref:`recurse ` *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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 .. _coveragestore_recurse: 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//coveragestores//file[.]`` The ``extension`` parameter specifies the type of coverage store. The following extensions are supported: .. list-table:: :header-rows: 1 * - Extension - Coveragestore * - geotiff - GeoTIFF * - worldimage - Geo referenced image (JPEG,PNG,TIF) * - imagemosaic - Image mosaic .. list-table:: :header-rows: 1 * - 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 :ref:`notes ` below. - - :ref:`configure `, :ref:`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 .. _coveragestore_file_put_notes: 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. .. _coverageName_parameter: 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//coveragestores//coverages[.]`` .. list-table:: :header-rows: 1 * - 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*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` ``/workspaces//coveragestores//coverages/[.]`` .. list-table:: :header-rows: 1 * - 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 - - - :ref:`recurse ` *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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 .. _coverage_recurse: 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 :ref:`SLD `. Operations ^^^^^^^^^^ ``/styles[.]`` .. list-table:: :header-rows: 1 * - 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 :ref:`notes ` below - - :ref:`name ` * - PUT - - 405 - - - * - DELETE - - 405 - - - :ref:`purge ` *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` .. _sld_post_put: When POSTing or PUTing a style as SLD, the ``Content-type`` header should be set to ``application/vnd.ogc.sld+xml``. .. _name_parameter: 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/[.]`` .. list-table:: :header-rows: 1 * - 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 :ref:`notes ` above - * - DELETE - Delete style ``s`` - 200 - - .. _purge_parameter: 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*: - :download:`SLD ` - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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[.]`` .. list-table:: :header-rows: 1 * - Method - Action - Return Code - Formats - Default Format * - GET - Return all layers - 200 - HTML, XML, JSON - HTML * - POST - - 405 - - * - PUT - - 405 - - * - DELETE - - 405 - - *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` ``/layers/[.]`` .. list-table:: :header-rows: 1 * - 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 - - - :ref:`recurse ` *Representations*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *Exceptions*: - GET for a layer that does not exist -> 404 - PUT that changes name of layer -> 403 - PUT that changes resource of layer -> 403 .. _layer_recurse: 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//styles[.]`` .. list-table:: :header-rows: 1 * - 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[.]`` .. list-table:: :header-rows: 1 * - 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*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` ``/layergroups/[.]`` .. list-table:: :header-rows: 1 * - 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*: - :download:`HTML ` - :download:`XML ` - :download:`JSON ` *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`` .. list-table:: :header-rows: 1 * - 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`` .. list-table:: :header-rows: 1 * - 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 - -