RESTful Configuration API

This page describes the proposed RESTful API for configuration of Geoserver datastores, etc.  It is very much a work in progress.  The main motivation for this interface is the need for users to be able to easily add new layers and for developers/more advanced users to do so programmatically

Motivation

The current means for automated manipulation of datastores and featuretypes is quite unwieldy (ie, simulating browser interaction with the configuration GUI.) By making the API cleaner, we can:

  • Create a public API for configuring Geoserver so that revising the configuration pages doesn't break third-party code
  • Encourage the development of better configuration interfaces by making them easier to develop
  • Provide better services for developers customizing Geoserver for their own needs

RESTful Philosophy

REST is an acronym for REpresentational State Transfer.  The basic idea of REST is to rely on a fixed set of operations on named resources, where the representation of each resource is the same for retrieving and setting information (that is, if you retrieve data in an XML format, you can send data back to the server in the same XML format to set it). In the case of this API, the fixed operations used are standard HTTP methods: GET, DELETE, PUT, POST, HEAD, etc. and the resources are therefore URIs where the host is the server running Geoserver. By defining a clear hierarchy for these resource URIs and maintaining a fixed set of possible operations on each, we keep the API straightforward and therefore easy to work with. See the table below for an elaboration on the details for this API.

Use Cases

  • Mike has a running Geoserver instance and a geotiff file that he would like to display. Technically, the geotiff file contains all the information Geoserver needs to display it; therefore he should only have to upload it and name the feature type to get Geoserver to display the map.
  • Dennis has manually created a new PostGIS database and inserted his data. He is a power user and does not want to use the web interface to add each individual feature type and set styling information. It should be possible for him to quickly create a script that adds all the feature types.
  • Phyllis has a cluster of servers running Geoserver and would like to keep configurations synchronized among them.  Rather than manually editing the configuration for each server via a web browser, she can create a simple script that will download the configuration from one master server and copy it to the others via the network.

Impact of Implementation

This API will be built on top of the current Java configuration API; therefore it will be a fairly thin wrapper around existing functionality. As such, it will be fairly robust in the face of potential changes to the Java configuration API in the future.

API Proposal

Currently Implemented

URI GET DELETE PUT POST
/rest/folders/ Retrieve a listing of all folders
-
-
Create a new folder with guaranteed clobbering prevention
/rest/folder/{folder}
Retrieve the configuration for the named folder
Delete the folder
Create or reconfigure the folder, clobbering any pre-existing configuration
-
/rest/folders/{folder}/layers
Retrieve a listing of layers in the named folder
- -
Create a new layer with guaranteed clobbering prevention
/rest/folders/{folder}/layers/{layer} Retrieve the configuration for the layer
De-configure the layer (will no longer be visible in  W*S requests)
Configure or reconfigure the layer, clobbering any pre-existing configuration.  The layer will be visible after the configuration is set.
-
/rest/folders/{folder}/layers/{layer}/data
Retrieve the data for the layer
Delete the layer
Provide/clobber the data for a layer and attempt to autoconfigure.
-
/rest/styles/ Retrieve a listing of all styles
-
-
-
/rest/styles/{style} Retrieve the style information as an SLD
Delete the style
Create or replace {style}
-

Proposed

URI GET DELETE PUT POST
/rest/layergroups/ Retrieve a listing of all layergroups
-
-
-
/rest/layergroups/{group}
Retrieve a list of the features in the group
Delete the layergroup
Create or reconfigure {layergroup}
-
/rest/projections/
Retrieve a listing of all projections [GEOS:2]
-
-
Upload a new projection
/rest/projections/{projection} [GEOS:3]
Retrieve the projection information for {projection}
Delete {projection}
Reconfigure an existing {projection}
-
/rest/services/
Retrieve a listing of configurable services. - - -
/rest/services/{service} Retrieve the current configuration for the specified service (WFS, WMS, WCS, or Global) - Overwrite the configuration for the specified service -

[GEOS:1] If a user wants to 'just upload' a shapefile or geotiff they can simply PUT to /api/folders/{folder}/layers/{layer}/data and Geoserver will autoconfigure it.  The layer can then be configured as normal.
[GEOS:2] Should we only list user-defined projections? 
[GEOS:3] Projection is the EPSG number

Specifying the output format

To make it easy to inspect the configuration using a regular web browser, the default output will be marginally formatted HTML. Other output formats, such as XML or JSON, can be obtained by appending ".json" or .xml (case sensitive). In a later iteration we would like to also check for the Accept request-header to determine the correct output format, while retaining the ability to override this with file extensions in the URL.

WCS

The table above does not currently include WCS. This will be added soon.

Implementation

There is currently a (partial) implementation of this API in a community module named RESTConfig. In order to try it out, just add -Prest,RESTConfig to your maven invocation when building GeoServer:

mvn install -Prest,RESTConfig # build GeoServer and include RESTConfig in the resulting .war file
mvn jetty:run -Prest,RESTConfig # from the web module, run GeoServer and include RESTConfig
mvn eclipse:eclipse -Prest,RESTConfig # produce Eclipse project files that include RESTConfig
View • Attachments (0) • Info