User Collaboration REST API

This is page is meant to flesh out some of the technical details described on the User Collaboration page, in particular nailing down the REST api for it. See User Collaboration web pages for technical details on needed html pages for collaboration.

Profiles

A users profile contains various bits of "collaborative information". This includes:

  • Data/layers/styles the user has uploaded w/ permissions
  • Maps the user has created w/ permissions
  • Comments, tags, ratings created by the user

Maps

Each user has the ability to create maps out of various layers and styles on the server. Each created map is stored on the server as a "context document". A context document is simply some serialized representation of which layers and styles make up the map, similar in nature to an OWS context document.

Clients will be able to access the context documents via the REST interface.

Statistics

Each time a layer is requested, useful statistics can be captured. Some examples include:

  • How many times the layer has been accessed
  • How recently the layer has been accessed
  • How many users have rated this layer
  • etc...

With these sorts of stats there are numerous queries that can be made:

  • What is the most popular layer?
  • What layer is being requested most frequently?
  • etc...

Internal Storage

In order to persist and access profile information and make queries against gathered statistics the information must be stored somewhere. The information in question lends itself to being stored in an internal database.

REST API

Path  GET (read)
POST (create)
PUT (update)
DELETE (delete)
/geoserver/collab/users Return a list of users
Create a new user.
405 405
/geoserver/collab/users/{username} Return a document about the user (profile information and links to her maps, layers and styles)
405 Update an existing user with new information (404 if the workspace doesn't exist).
Remove an existing user.
/geoserver/collab/users/{username}/layers Return a list of layers (enabled and disabled) uploaded by a particular user
405 (creation is through the general rest api, and will pick up the user from the authentication credentials)
405 405
/geoserver/collab/users/{username}/layers/{name} Return configuration information about a named layer.
405 405 (update through general rest api).
405 (delete through rest api)
Path
GET (read)
POST (create)
PUT (update)
DELETE (delete)
/geoserver/collab/users/{username}/maps Return a list of a user's maps
405 (creation through /geoserver/collab/maps)
405
405
/geoserver/collab/users/{username}/maps/{name} Return a map (json dump, ows context document, and perhaps eventually html with embedded JS map, or a straigh js map).  Should also do rel="self" to canonical url at /collab/maps/{name}
405
405 (updates through /collab/maps/{name}
405
/geoserver/collab/users/{username}/styles Return a list of styles created by the user.
405
405
405
/geoserver/collab/users/{username}/styles/{name}
Return information about an existing style.  (Can be represented as sld:FeatureTypeStyle.)   Should do rel="self" to canonical url at /geoserver/rest/styles/{stylename}
405
405 (through canonical location)
405 (through canonical location
/geoserver/collab/users/{username}/layers Return a list of layers (enabled and disabled) uploaded by a particular user
405 (creation is through the general rest api, and will pick up the user from the authentication credentials)
405 405
/geoserver/collab/users/{username}/layers/{name} Return configuration information about a named layer.
405 405 (update through general rest api).
405 (delete through rest api)
Path
GET (read)
POST (create)
PUT (update)
DELETE (delete)
/geoserver/collab/maps Return a list of all maps (created by all users)
Add a new map.
405
405
/geoserver/collab/maps/{name} Return a map (json dump, ows context document, and perhaps eventually html with embedded JS map, or a straight js map).
405
Update an existing map with new information (404 if the map doesn't exist).
Remove a named map.
/geoserver/rest/styles (exists already in rest api)
Return a list of styles created by all users.
Create a new style.  (register in catalog and record user who uploaded it based on authentication)
405
405
/geoserver/rest/styles/{name} (exists already in rest api) Return information about an existing style.  (Can be represented as sld, html and json.)
405
Update information about an existing style (404 if it doesn't exist).
Remove a named style.
/geoserver/collab/users/{username}/marks Returns a list of content (maps/styles/layers) actively metadata marked by this user (tagged/rated/commented)
Create a new metadata mark.  See below for first attempt at a mark document
405
405
/geoserver/collab/users/{username}/marks/{markhash} Return information about a mark.  See below for a first attempt at a mark document
405
Update information about a mark (404 if it doesn't exist)
Remove a mark
/geoserver/collab/users/{username}/tags Return a list of tags made by this user
405 (tags are only created in marks)
405
405
/geoserver/collab/users/{username}/tags/{tagname} Returns a list of all marks made by this user that contain the tagname (xml document with links to the actual marks).
405
405
405

The mark document would look something like

GET http://mysite.org/geoserver/users/cholmes/marks/a211528fb5108cddaa4b0d3aeccdbdcf

<?xml version="1.0"?>
  <mark url="http://mysite.org/geoserver/users/jdeolive/maps/2xf35g" time="2005-10-21T19:07:30Z">
    <description>  Example of a geo data mark     </description>
       <tags count="2">
         <tag name="example" href="mysite.org/geoserver/users/cholmes/tags/example"/>
         <tag name="test" href="mysite.org/geoserver/users/cholmes/tags/test"/>
       </tags>
       <rating value="5"/>
       <comments>
         <comment time="2005-10-21T19:07:30Z">This map is so cool.</comment>
       </comments>
  </mark>

The mark resource is the hash of the resource being marked.  This is the same way delicious does it.  Theoretically this lets a user rate any piece of content on the web, but we'll limit it to maps, styles and layers.  I think to be more restful we should probably have /comments/ under the hash resource (I'm just too tired right now to fill it out).  Rating I believe can stay in the mark hash, because there's only one.  Tags is a list of names, and refers to a list of all the tags that a user has made.

The other pattern that needs fleshing out is how to obtain ratings/tags/comments from a layer, a map or a style.  Need to research more relevant patterns, but I think some sort of 'meta' document could provide the overall rating, the number of views, a list of the tags, and a list of the comments.  These would not be editable, they would only reflect the updates done on each user's 'marks', and would refer back to the individual marks and tags that were done.

Further implementation thoughts

The one area this does touch existing stuff a bit is with the uploading and modification of styles and layers.  Layers have to be registered in the catalog.  And talking to Rollie it seems like putting styles in the catalog too would be a good thing so we can actually list the styles available for a layer for other clients (since if the catalog has knowledge we can put it in the WMS capabilities document).  I'm still going back and forth on this, it might be better to just keep them completely in the collab resource area.  The thing we do need to do for users uploading layers (shp and geotiff) and styles is to have the core rest api listen to which user is authenticated.  We can perhaps make an extension point for another module to get at that info?  Since we probably want to just track that in the user database, not somewhere in core?  We will need the user api to know what layers/styles/maps are owned by a person.

Added by Justin Deoliveira, last edited by Andrea Aime on May 20, 2009  (view change)
View Attachments (2) Info