Managing Layers through the REST API¶

The REST API for Layer management provides a RESTful interface through which clients can programatically add, modify, or remove cached Layers.

Layers list¶

/rest/seed/layers.xml

Method	Action	Return Code	Formats
GET	Return the list of available layers	200	XML
POST		400
PUT		400
DELETE		400

Note: JSON representation is intentionally left aside as the library used for JSON marshaling has issues with multi-valued properties such as parameterFilters.

Sample request:

curl -u geowebcache:secured  "http://localhost:8080/geowebcache/rest/layers"

Sample response:

<layers>
 <layer>
   <name>img states</name>
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geowebcache/rest/layers/img+states.xml" type="text/xml"/>
 </layer>
 <layer>
   <name>raster test layer</name>
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geowebcache/rest/layers/raster+test+layer.xml" type="text/xml"/>
 </layer>
 <layer>
   <name>topp:states</name>
   <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geowebcache/rest/layers/topp%3Astates.xml" type="text/xml"/>
 </layer>
</layers>

Layer Operations¶

/rest/seed/layers/<layer>.xml

Method	Action	Return Code	Formats
GET	Return the XML representation of the Layer	200	XML
POST	Modify the definition/configuration of a Layer	200	XML
PUT	Add a new Layer	200	XML
DELETE	Delete a Layer	200

Representations:

Note: JSON representation is intentionally left aside as the library used for JSON marshaling has issues with multi-valued properties such as parameterFilters.

REST API for Layers, cURL Examples¶

The examples in this section use the cURL utility, which is a handy command line tool for executing HTTP requests and transferring files. Though cURL is used the examples apply to any HTTP-capable tool or library.

Add Layer¶

Sample request:

Given a layer.xml file as the following:

<wmsLayer>
  <name>layer1</name>
  <mimeFormats>
    <string>image/png</string>
  </mimeFormats>
  <gridSubsets>
    <gridSubset>
      <gridSetName>EPSG:900913</gridSetName>
    </gridSubset>
  </gridSubsets>
  <wmsUrl>
    <string>http://localhost:8080/geoserver/wms</string>
  </wmsUrl>
  <wmsLayers>topp:states</wmsLayers>
</wmsLayer>

curl -v -u geowebcache:secured -XPUT -H "Content-type: text/xml" -d @layer.xml  "http://localhost:8080/geowebcache/rest/layers/layer1.xml"

Or if using the GeoServer integrated version of GeoWebCache:

curl -v -u user:password -XPUT -H "Content-type: text/xml" -d @layer.xml  "http://localhost:8080/geoserver/gwc/rest/layers/layer1.xml"

Note that the addressed resource layer1.xml, without the .xml extension, must match the name of the layer in the xml representation.

Modify Layer¶

Now, make some modifications to the layer definition on the layer.xml file:

<wmsLayer>
  <name>layer1</name>
  <mimeFormats>
    <string>image/png</string>
    <string>image/jpeg</string>
    <string>image/gif</string>
  </mimeFormats>
  <gridSubsets>
    <gridSubset>
      <gridSetName>EPSG:900913</gridSetName>
    </gridSubset>
    <gridSubset>
      <gridSetName>EPSG:4326</gridSetName>
    </gridSubset>
  </gridSubsets>
  <wmsUrl>
    <string>http://localhost:8080/geoserver/wms</string>
  </wmsUrl>
  <wmsLayers>topp:states,nurc:Img_Sample</wmsLayers>
</wmsLayer>

And use the HTTP POST method instead:

curl -v -u geowebcache:secured -XPOST -H "Content-type: text/xml" -d @layer.xml  "http://localhost:8080/geoserver/gwc/rest/layers/layer1.xml"

Delete Layer¶

Finally, to delete a layer, use the HTTP DELETE method against the layer resource:

curl -v -u geowebcache:secured -XDELETE "http://localhost:8080/geoserver/gwc/rest/layers/layer1.xml"