The most recent information on the redesign of the GeoServer REST API has moved. This page is more for background and historical purposes.

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.

We try to follow the following rules in designing the API:

• GET does not make any persistent changes on the server; it only retrieves data.  Query parameters may be used to filter or otherwise create a special view of that data, but nothing is persisted.
• POST is the only method that can be used to create a resource, and the created resource will be a child of the resource to which the POST request was made.  That is, POST /foo creates a resource like /foo/bar. The response to a successful post request should be a '201 Created' with a Location header specifying the new resource's URL.
• PUT is the only way to update an existing resource.
• DELETE removes the resource specified.
• A URL may be suffixed with a . followed by a file extension to request a particular format; ie foo.json to request an object in JavaScript Object Notaton. If this is omitted, a reasonable default (usually HTML) is used.

Use Cases

Some possible use cases and sample code for each are listed at RESTFul Configuration API Use Cases

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