GSIP 137

GSIP 137 - ResourceStore Rest API

Overview

Proposed By

Niels Charlier

Assigned to Release

This proposal is for GeoServer 2.9.0 and later

State

• Under Discussion
• In Progress
• Completed
• Rejected
• Deferred

Motivation

Once the data directory has been ported to a jdbcresourcestore, there is no way to manually edit resources and directories in the resource store. Some of the resources can be manipulated through specific rest API's, but not all of them.

Example of configuration information stored as resources:

• icons and fonts used during styling
• projection support files (such as grid sets)
• templates used for GetFeatureInfo
• printing templates

Proposal

/resource</path/to/resource>[?arguments]

Arguments

• (GET) format = xml | html | json
• (GET) operation = default | metadata
• (PUT) operation = default | copy | move

Methods

• GET
  • Download a resource OR return a list of children if it is directory
  • return 200
  • formats (for directory | metadata): HTML (default), XML, JSON. For resource downloads, mime type will be guessed from name and then content. If both fail, "application/octet-stream" will be returned.
• GET with [operation=metadata]
  • Get metadata of resource
  • return 200
  • formats (for directory | metadata): HTML (default), XML, JSON
• PUT
  • Upload a resource, create directories on the fly (overwrite if exists)
  • return 200 (exists) 201 (new)
• PUT with [operation=copy/move]
  • Copy/move a resource (source path specified in body), create directories on the fly (overwrite if exists). Copying is not supported for directories.
  • return 200 (exists) 201 (new)
• DELETE
  • Delete a resource (recursive if directory)
  • return 200

Also: research support for HEAD requests for metadata.

Exceptions

• GET or DELETE for a resource that does not exist
  • return 404
• PUT file to directory / copy directory
  • return 405
• PUT copy/move with source path doesn't exist
  • return 404
• POST
  • return 405

Format

Examples are given in XML. The JSON and HTML formats are analogue.

Metadata

   <ResourceMetaData>
      <name> nameOfFile </name>
      <parent> <path> path/to/parent </path>
           <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate"
      href="http://localhost:8080/geoserver/rest/resource/path/to/parent?operation=metadata&format=xml" 
            type="application/xml"/>
      </parent>
      <lastModified> date </lastModified>
      <type> undefined | resource | directory </type>
  </ResourceMetaData>

Directories

<ResourceDirectory>`
      <name> nameOfDirectory </name>
      <parent> <path> path/to/parent </path>
           <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate"
      href="http://localhost:8080/geoserver/rest/resource/path/to/parent?operation=metadata&format=xml" 
            type="application/xml"/>
      </parent>
      <lastModified> date </lastModified>
      <children>
          <child>
                  <name> ... </name>
                  <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate"
                   href="http://localhost:8080/geoserver/rest/resource/path/to/child"/>
          </child>
          <child>
                  ...
          </child>
          ...
      </children>` 
</ResourceDirectory>

Feedback

• Q: Do we need both a resource and a dir endpoint?
• A: made changes to use one endpoint

Email Discussion:

• Proposal: ResourceStore Rest API
• New REST community module supporting resumable uploads
• Jdbc resource store

Backwards Compatibility

This is new functionality, does not apply.

Voting

Project Steering Committee:

• Alessio Fabiani: +1
• Andrea Aime: +1
• Ben Caradoc-Davies: +1
• Christian Mueller:
• Ian Turton: +1
• Jody Garnett: +1
• Jukka Rahkonen: +0
• Kevin Smith: +1
• Simone Giannecchini:

Committers:

Links

https://osgeo-org.atlassian.net/browse/GEOS-7407