Skip to content

Developing based on GeoServer restful api

GeoServer is an open source server for sharing geospatial data. It's designed for interoperability, it publishes data from any major spatial data source using open standards.

Restful file

GeoServer provides a RESTful interface through which clients can retrieve information about an instance and make configuration changes. Using the REST interface's simple HTTP calls, clients can configure GeoServer without needing to use the Web administration interface.

REST is an acronym for "REpresentational State Transfer". REST adopts a fixed set of operations on named resources, where the representation of each resource is the same for retrieving and setting information. In other words, you can retrieve (read) data in an XML format and also send data back to the server in similar XML format in order to set (write) changes to the system.

Operations on resources are implemented with the standard primitives of HTTP: GET to read; and PUT, POST, and DELETE to write changes. Each resource is represented as a URL, such as http://GEOSERVER_HOME/rest/workspaces/topp.

Steps to configure authentication

We want to developing based on GeoServer restful api, the first thing would be configuring GeoServer to accept authentication information passed by HTTP header attribute(s).

Rest properties file

The REST process has its own security configuration that needs to be setup in addition to the web interface user. These are different configurations and are setup in different spots. The REST configuration does use that same users you have configured in the web interface it just doesn't use the access rules that you would have set up.

To know about the permissions you need to view a file in the directory [Geoserver_data}/security called rest.properties. Restful file

Rest properties

From the properties file content, we can see all the rest api will need admin user authentication. Restful properties

Users, groups and roles

From the GeoServer web ui, we can define users, groups and roles. Users and roles

Rest test

If we try to test any GeoServer rest api without any configuration, we will meet a 401 error because of no authentication. Restful test 401

Authentication filters

Click the Authentication link located under the Security section of the navigation sidebar. Scroll down to the Authentication Filters panel and click the Add new link. Restful file

Add authentication filter

Click the HTTP Header link and set "Name" to anything you'd like, Set Request header attribute to to a random token other than "user" or "admin". It's a obscure header attribute name which is a shared secret between the proxy and GeoServer. Set Role source to "User group service" and name of the user group service to "default". Restful file

Authentication filter chains

Go back to the Authentication link and scroll down to the Filter Chains panel. Notice the rest filter chain here and click into it. Restful file

Configure rest filter chain

Scroll down to the Chain filters panel. Drag the newly added authentication filter to the selected part and position it before all other filters. Restful file

Rest test successful

Try the rest api again with specified header which is the Request header attribute we just set and with the value of "admin". Restful file

Restful APIs

The full restful api list can be found here.

  • List workspaces

    GET http://<url>/geoserver/rest/workspaces

    Response

  • List layers in a workspace

    GET http://<url>/geoserver/rest/workspaces/<workspaceName>/layers

    Response

  • List coverage stores which describe the raster data source

    GET http://<url>/geoserver/rest/workspaces/<workspaceName>/coveragestores

    Response

  • List styles in a workspace

    GET http://<url>/geoserver/rest/workspaces/<workspaceName>/styles

    Response

  • List styles under a layer

    GET http://<url>/geoserver/rest/layers/<layerName>/styles

    Response

  • List styles

    GET http://<url>/geoserver/rest/styles

    Response

  • Get a workspace

    GET http://<url>/geoserver/rest/workspaces/<workspaceName>

    Response

  • Get a layer in a workspace

    GET http://<url>/geoserver/rest/workspaces/<workspaceName>/layers/<layerName>

    Response

  • Get a coverage store in a workspace

    GET http://<url>/geoserver/rest/workspaces/<workspaceName>/coveragestores/<storeName>

    Response

  • Get a sld style in a workspace

    GET http://<url>/geoserver/rest/workspaces/<workspaceName>/styles/<styleName>.sld

    Response

  • Get the info of a layer in a workspace

    GET http://<url>/geoserver/rest/workspaces/<workspaceName>/coveragestores/<storeName>>/coverages/<layerName>.json

    Response

  • Create a workspace

    POST http://<url>/geoserver/rest/workspaces

    Response

  • Create a coverage store in a workspace

    POST http://<url>/geoserver/rest/workspaces/<workspaceName>/coveragestores?configure=all

    Response

  • Create a layer in a workspace

    POST http://<url>/geoserver/rest/workspaces/<workspaceName>/coveragestores/<storeName>/coverages?configure=all&recalculate=nativebbox,latlonbbox

    Response

  • Create a layer with default style in a workspace

    POST http://<url>/geoserver/rest/workspaces/<workspaceName>/coveragestores/<storeName>/coverages?configure=all&recalculate=nativebbox,latlonbbox

    Response

  • Create a sld style

    POST http://<url>/geoserver/rest/styles?name=<styleName>

    Response

  • Specify the default style for a layer

    PUT http://<url>/geoserver/rest/layers/<workspaceName>:<layerName>

    Response

  • Modify a sld style content

    PUT http://<url>/geoserver/rest/styles/<styleName>.xml?name=<styleName>

    Response

  • Delete a workspace

    DELETE http://<url>/geoserver/rest/workspaces/<workspaceName>?recurse=true

    Response

  • Delete a coverage store in a workspace

    DELETE http://<url>/geoserver/rest/workspaces/<workspaceName>/coveragestores/<storeName>.geotiff

    Response

  • Delete a layer

    DELETE http://<url>/geoserver/rest/workspaces/<workspaceName>/coveragestores/<storeName>/coverages/<layerName>?recurse=true

    Response

  • Delete a style

    DELETE http://<url>/geoserver/rest/styles/<styleName>

    Response

Other Service APIs

After you have served your raster layer on the GeoServer, you are able to get some information by WMS/WMTS protocol and so on.

  • WMS GetFeatureInfo

    GET http://<url>/geoserver/gwc/service/wms?REQUEST=GetFeatureInfo&SERVICE=WMS&SRS=<SRS>&STYLES=&TRANSPARENT=&VERSION=1.0.0&FORMAT=image/png&BBOX=<BBOX>&HEIGHT=<HEIGHT>&WIDTH=<WIDTH>&LAYERS=<workspaceName>:<layerName>&QUERY_LAYERS=<workspaceName>:<layerName>&INFO_FORMAT=application/json&X=<X>&Y=<Y>

    Response

  • WMS GetLegendGraphic

    GET http://<url>/geoserver/gwc/service/wms?SERVICE=WMS&VERSION=1.0.0&REQUEST=GetLegendGraphic&FORMAT=image/png&WIDTH=20&HEIGHT=20&layer=<workspaceName>:<layerName>[&style=<styleName> or &sld_body=<sldContent>]

    Response

  • WMS GetMap

    GET http://<url>/geoserver/gwc/service/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&TRANSPARENT=true&LAYERS=<workspaceName>:<layerName>&STYLES=<styleName>&FORMAT_OPTIONS=layout:style-editor-legend;fontAntiAliasing:true&LEGEND_OPTIONS=forceLabels:on;fontAntiAliasing:true&EXCEPTIONS=application/vnd.ogc.se_inimage&CRS=<CRS>&WIDTH=688&HEIGHT=768&BBOX=<BBOX>

    Response