Permissions API

GeoIQ has a robust permissions system that allows users to grant the ability for groups to perform specific actions on datasets and maps that they own.

Set permissions

You can set permissions for a dataset or map by updating the permissions attribute.

API URL

http://geocommons.com/:object/:id.json

• object can be “datasets”, “overlays”, or “maps”
• id@ is the unique id of the @object

HTTP method
PUT

authentication requried?
Yes

URL formats
json

Parameters

• group_id – (required) id of a group for which the permissions should be set. Can also be “everyone”
• permissions – (required) a set of individual permission options:
  • view – the group or user is allowed to search and view the metadata for this object (default: false)
  • download – the group or user is allowed to download the data for this object (default: false)
  • edit – the group or user is allowed to edit the data for this object (default: false)

Examples

• Status: See Response Codes Below
• Content Body:

{
  permissions: [{
    group_id: 12
    permissions: { 
      view: true,
      download: true,
      edit: false
    }
  }]
}

Examples

Updating a Dataset with permissions defined in a JSON content body:

{
  permissions: [ 
  { group_id: 12
    permissions: { 
      view: true,
      download: true,
      edit: false
    }
  },
  { group_id: "everyone"
    permissions: {
      view: true,
      download: true,
      edit: false
    }
  }]
}

curl -u "admin:password" -X PUT -i --data "@new_permissions.json"  --header Content-Type:application/json http://geocommons.com/datasets/140.json

or via key/value pairs:

curl -u "admin:password" -X PUT -i --header "Content-Type:application/json" -d "permissions[][group_id]=12" -d "permissions[][permissions][view]=true" -d "permissions[][permissions][download]=true" -d "permissions[][group_id]=everyone" -d "permissions[][permissions][view]=true" -d "permissions[][permissions][download]=true"  http://geocommons.com/datasets/140.json

Note: permissions will default to false if not specified.

Combined Calls

Permissions can also be included as parameters on other calls made via the Data API

POST http://geocommons.com/datasets.json

Examples

{
 title: "New Overlay",
 permissions: [
{
  group_id: "12",
  permissions: {
    view: true,
    download: true,
    edit: false
  }
}
]}

Response Codes

200 OK

If the user request to set permissions has worked, then GeoIQ will respond with 200 OK. This is OK since it isn’t apparent if new permissions were created, deleted, or just modified.

400 Bad Request

If the API request was not formed correctly (e.g. bad JSON syntax), GeoIQ will respond with 400 Bad Request.

401 Unauthorized

If the user is not logged in at all, GeoIQ will respond with 401 Unauthorized. If the user is logged in, and they are not able to change permissions, use 403 Forbidden below.

404 Not Found

If a user attempts to change permissions on a GeoIQ dataset or map that does not exist, then GeoIQ will respond with 404 Not Found.