Managing Layers¶

The GeoWebCache REST API provides a RESTful interface through which users can add, modify, or remove cached layers.

Note

JSON is not recommended for managing layers as the JSON library has a number of issues with multi-valued properties such as “parameterFilters”.

Layer list¶

URL: /gwc/rest/seed/layers.xml

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

The following example will request a full list of layers:

curl -u admin:geoserver "http://localhost:8080/geoserver/gwc/rest/layers"

<layers>
  <layer>
    <name>img states</name>
    <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/gwc/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/geoserver/gwc/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/geoserver/gwc/rest/layers/topp%3Astates.xml" type="text/xml"/>
  </layer>
 </layers>

Layer Operations¶

URL: /gwc/rest/seed/layers/<layer>.xml

Note

JSON is not recommended for managing layers as the JSON library has a number of issues with multi-valued properties such as “parameterFilters”.

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

Note

There are two different representations for cached layers, depending on whether the tile layer is created from the GeoServer WMS layer or layer group (GeoServerLayer), or is configured in geowebcache.xml as a regular GWC layer (wmsLayer). A GeoServer layer is referred to as a GeoServerLayer and contains no image data source information such as origin WMS URL.

Representations:

GeoWebCache (wmsLayer) XML minimal
GeoWebCache (wmsLayer) XML
GeoServer (GeoServerLayer) XML minimal
GeoServer (GeoServerLayer) XML

The examples below use the cURL tool, though the examples apply to any HTTP-capable tool or library.

Adding a GeoWebCache layer¶

The following example will add a new layer to GeoWebCache:

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

The layer.xml file is defined as the following:

<wmsLayer>
  <name>newlayer</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>

Note

The addressed resource (newlayer in this example) must match the name of the layer in the XML representation.

Adding a GeoServer layer¶

The following example will add a new layer to both GeoServer and GeoWebCache:

curl -v -u admin:geoserver -XPUT -H "Content-type: text/xml" -d @poi.xml  "http://localhost:8080/geoserver/gwc/rest/layers/tiger:poi.xml"

The poi.xml file is defined as the following:

<GeoServerLayer>
  <id>LayerInfoImpl--570ae188:124761b8d78:-7fd0</id>
  <enabled>true</enabled>
  <name>tiger:poi</name>
  <mimeFormats>
    <string>image/png8</string>
  </mimeFormats>
  <gridSubsets>
    <gridSubset>
      <gridSetName>GoogleCRS84Quad</gridSetName>
      <zoomStart>0</zoomStart>
      <zoomStop>14</zoomStop>
      <minCachedLevel>1</minCachedLevel>
      <maxCachedLevel>9</maxCachedLevel>
    </gridSubset>
  </gridSubsets>
  <metaWidthHeight>
    <int>4</int>
    <int>4</int>
  </metaWidthHeight>
  <gutter>50</gutter>
  <autoCacheStyles>true</autoCacheStyles>
</GeoServerLayer>

Note

The addressed resource ( tiger:poi in this example) must match the name of the layer in the XML representation, as well as the name of an existing GeoServer layer or layer group.

Modifying a layer¶

This example modifies the layer definition via the layer.xml file. The request adds a parameter filter and a grid subset to the existing tiger:poi tile layer:

<GeoServerLayer>
 <enabled>true</enabled>
 <name>tiger:poi</name>
 <mimeFormats>
   <string>image/png8</string>
 </mimeFormats>
 <gridSubsets>
   <gridSubset>
     <gridSetName>GoogleCRS84Quad</gridSetName>
     <zoomStart>0</zoomStart>
     <zoomStop>14</zoomStop>
     <minCachedLevel>1</minCachedLevel>
     <maxCachedLevel>9</maxCachedLevel>
   </gridSubset>
   <gridSubset>
     <gridSetName>EPSG:900913</gridSetName>
     <extent>
       <coords>
         <double>-8238959.403861314</double>
         <double>4969300.121476209</double>
         <double>-8237812.689219721</double>
         <double>4971112.167757057</double>
       </coords>
     </extent>
   </gridSubset>
 </gridSubsets>
 <metaWidthHeight>
   <int>4</int>
   <int>4</int>
 </metaWidthHeight>
 <parameterFilters>
   <floatParameterFilter>
     <key>ELEVATION</key>
     <defaultValue>0.0</defaultValue>
     <values>
       <float>0.0</float>
       <float>1.0</float>
       <float>2.0</float>
       <float>3.0</float>
       <float>4.0</float>
     </values>
     <threshold>1.0E-3</threshold>
   </floatParameterFilter>
 </parameterFilters>
 <gutter>50</gutter>
 <autoCacheStyles>true</autoCacheStyles>
</GeoServerLayer>

Instead of PUT, use the HTTP POST method instead:

curl -v -u admin:geoserver -XPOST -H "Content-type: text/xml" -d @poi.xml  "http://localhost:8080/geoserver/gwc/rest/layers/tiger:poi.xml"

Deleting a layer¶

Deleting a GeoWebCache tile layer deletes the layer configuration as well as the layer’s disk cache. No tile images will remain in the cache directory after deleting a tile layer.

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

curl -v -u admin:geoserver -XDELETE "http://localhost:8080/geoserver/gwc/rest/layers/newlayer.xml"

Note

If trying to delete a tile layer that is an integrated GeoServerLayer, only the GeoWebCache layer definition will be deleted; the GeoServer definition is left untouched. To delete a layer in GeoServer, use the GeoServer REST configuration to manipulate GeoServer resources.

On the other hand, deleting a GeoServer layer via the GeoServer REST API will automatically delete the associated tile layer.