Skip to content

REST_API

Jump to bottom Edit New page
Juan Wajnerman edited this page Sep 2, 2014 · 7 revisions

Table of Contents

<>

Accessing the API

The APIs authenticates with HTTP basic, and you must provide a user email and password.

For long-term system integration, you may want to create a user that is only used for API purposes so it is less affected by resetting passwords, permission changes, etc than a person.

    • API in within internal staging releases is subject to changes without versioning. Changes to public releases will be versioned and documented. The documentation below may be out of sync with any specific deployed version in staging.

If you have questions or find issues please feel free to contact discuss here: InSTEDD Technology Users Community (Google Group)**

Getting your collection ID

Unless you want to use discovery APIs, you can get started by

  1. Going to your collection property tabs
  2. Under the 'Overview' tab look at the API Access section
  3. You will have links to the query API, and you can see your collection ID in that URL.

You can get your collections by querying

    • /collections.json**

Format

The format can be specified by the extension of the request. For example,

The GeoJSON format has a different URL:

GeoRSS

The RSS return format fulfills the GeoRSS specification using the //http://www.w3.org/2003/01/geo/wgs84\_pos// namespace, and latitude and longitude fields are presented in geo:lat and geo:long elements corresponding to that namespace. This makes it easy to consume the data from GeoRSS compatible tools. Keep in mind the consuming application will need to provide the login credentials unless the collection has a public layer.

Queries

//Note: For these examples we will assume you have an Collection ID of 350//

Getting all sites in a collection: **/api/collections/350.json**

Filtering

ResourceMap allows filtering sites by all kinds of properties defined in the collection. It also allows counting, sorting and paging.

More information here

A count of items in the collection can be obtained by calling:

    • api/collections/350/count.json**

Getting one site

You can retrieve only one item by ID the following way:

    • /api/sites/.json**
    • /api/sites/.rss**

//Note: The ID field is the internal system ID of the item, not some field you created and treat as an ID field.//

Versioning

ResourceMap stores a site version every time a change is made. These versions are called "histories". Each history has an autoincremental version number and valid_from/valid_to fields that indicate the from/to dates in which this version was the current one. Each history contains the complete site information, and not only the changed values. It also includes the email of the user that performed the last update in the site.

To get all histories of a site:

To get a particular site's version:

//Note: You need to be the admin of the collection to be allowed to query site histories//

Sample return data:

GET to http://servername/api/collections/428/sites/119815/histories.json?version=3

Metadata

//Note: You need to be the admin of the collection to be allowed to query the metadata information//

You can get a definition of your layer metadata here:

    • /collections/350/layers.json**

This will return all metadata about fields (codes, lookup values and codes, etc) in the collection with ID = 350, grouped in layers.

For more specific actions follow this link

Security Info

You can get which users have access to which layers here:

    • /collections/350/memberships.json**

This will return all the users that have access to the system collection with ID= 350, and their permissions to read and write to different layers and sites. Of course, accessing this information is only possible if the login used in the request has permissions as an owner of the collection.

This is a sample return data for membership's query:

,

 {"user_id":7,"user_display_name":"[email protected]","admin":false,    "layers":[],    "sites":{      "read":{        "all_sites":false,        "some_sites":[          {"id":"8376","name":"Site 3"},          {"id":"11487","name":"Site 4"}]},      "write":{        "all_sites":false,        "some_sites":[          {"id":"11487","name":"Site 4"}]}}}]

}}}

Example Return Data

Here are some examples so you can see the JSON and RSS formats:

    • /api/collections/350.json**
    • /api/collections/350.rss**

GeoJson Example with one site only:

Activity Stream

You can query the activity rss feed for your collections via API.

The URL is **/api/activity.rss**

This feed will show all user's activity in all collections in which you are a member.

Optionally you can specify in what kind of activities and in which collections are you interested.

    • /api/activity.rss?collection_ids[]=32&collection_ids[]=31** : filters all kind of activity in collection with internal id 32 or 31

The options for filtering kind of activity are:

  • collection,created
  • collection,csv_imported
  • collection,imported
  • layer,created
  • layer,changed
  • layer,deleted
  • site,created
  • site,changed
  • site,deleted

For exaple:

    • /api/activity.rss?kinds[]=site,deleted&kinds[]=layer,deleted** : filters sites and layer delete action of all users in all collections.

You can also combine collection_ids and kinds in the same query.

Update Site

Single property update in Site

You can update a single property in a Site you should do a POST to:

//Note: SITE-ID is the internal system ID of the site

And you should pass the parameters you want to update:

    • ?es_code=350&value=Mr. Richard

// 350 is the propery internal ID and Mr. Richard is the new value for the property

Param format

      • Text Fields: ** ?es_code=350&value=Changed Text
      • Numeric Fields: ** ?es_code=350&value=1234
      • Select One Fields: ** ?es_code=350&value=2 // 2 is the internal ID for the option
      • Select Many Fields: ** ?es_code=350&value[]=2&value[]=1 // 1 and 2 are the internal ID for the options
      • Hierarchy Fields: ** ?es_code=350&value[]=2 // 2 is the internal ID for the hierarchy
      • Date Fields: ** ?es_code=350&value[]=12/26/2012 // The date is in MM/DD/YYYY format
      • Site Fields: ** ?es_code=350&value=12456 // 12456 is the referred Site internal ID
      • Phone Fields: ** ?es_code=350&value=15555555555

Deleting values

For deleting the field's value, simply do not pass the parameter "value".

    • ?es_code=350** : will delete the value for property with internal ID = 350.

This works for all field's types.

Changing Site's name or location

For changing name or location, you should do a PUT to:

With parameters:

    • "site"=>"{\"name\":\"New Site Name\"}

or:

    • "site"=>"{\"lat\":-12.834253993970767,\"lng\":30.15640980316266}

Full update

For changing more than one property, you should do a PUT to

With parameters:

    • "site"=>"{\"id\":,\"name\":\"New Site Name\",\"lat\":-12.83425399397077,\"lng\":30.15640980316266,\"properties\":{\"206\":\"new text value\",\"207\":\"12345\",\"208\":2}}

Each property value format depends on the field's type. The format is specified in "Param format" section.

Partial update

The action you need to use is

**http://servername/collections/:collection_id/sites/:site_id/partial_update** via POST

Using this one parameters included in the request are updated and the ones that are not present are not modified.

The format of the parameters are the same of in "Full Update" section above.

Create Site

You can create a new site by issuing a POST to:

http://SERVER_NAME/collections/COLLECTION_ID/sites.json

Example URL:

http://resourcemap.instedd.org/collections/485/sites.json

Authentication mechanism: Basic (see Accessing the API)

Content-Type: text/html

Params

    • site (required)**: a JSON object sent as form-data. Sites have some built-in fields (available in every site of every collection in Resource Map) and others which are collection specific.

Built-in fields are:

  • name (text): the name of the site to be created. Required.
  • lat (decimal): latitude of the site to be created. Optional.
  • lng (decimal): longitude of the site to be created. Optional.

Collection specific site fields are inside the **properties** property. Since there are different types of fields (text, numeric, date, etc.), the validation criteria for each value provided inside the **properties** field varies.

Collection specific site fields are of the form **"FIELD_ID":"VALUE"**, where FIELD_ID is an integer. To retrieve field ids of your collection specific site fields see [API for Metadata queries](API for Metadata queries "wikilink").

Request

Here's an example raw HTTP request that creates a site on an example collection:

Remarks:

  • Notice the format of the Authorization header, which is where we state that we're using Basic Auth.
  • Content-Disposition is where you specify that you're sending a form-data param.
  • The param name is specified as **name="site"**.
  • The site JSON object is built as discussed above. Pay special attention to the properties field: in this case, the request will only succeed if the target collection has specific fields with ids 2000, 2001 and 2002.

Response

If the request to create a site succeeds, Resource Map will return a JSON object with the complete representation of the site just created:

Delete Site

For deleting a site, do a DELETE to:

Metadata Update

You should be a collection admin for being able to modify metadata.

Creating new layer

To create a new layer, do a POST to:

//Note: You need to set the Content-Type Header to "application/json"

Parameters:

This will create a new field for each type.

Updating existing Layer

To update an existing layer, you should do a PUT to:

//Note: You need to set the Content-Type Header to "application/json"

//Note: In this example we are assuming that the layer_id of the layer you want to update is 59 and the fields' ids are form 241 to 250. All ids should correspond to existing layers and fields.

Parameters:

Deleting a Layer

To delete an existing layer you should do a DELETE to:

Security Info Update

You should be a collection admin for being able to modify permissions.

Creating New Membership

To create a new membership to a collection for a user, do a POST to:

Parameters: {"email"=>"[email protected]", "collection_id"=>""}

This email must be the email of a existing user in the system.

This will return the operation status and the user_id:

{"status":"added","user_id":6,"user_display_name":"[email protected]"}

Setting admin permission

After creating the membership for the user, if you want to make him/her collection's admin you should do a POST to:

Revoking admin permission

Revoking admin permission is similar: Do a POST to:

Setting layer access

Users can have **read** and/or **write** permission to a collection's layer.

A POST to:

With parameters:

    • {"layer_id"=>"58", "verb"=>"read", "access"=>"true" }

Will create a read permission for the user with internal ID = to the layer with internal ID = 58 of the collection with internal ID = . This means that he/she will be able to see all site's properties inside the layer 58, but he/she won't be able to change them.

With parameters:

    • {"layer_id"=>"58", "verb"=>"write", "access"=>"true"}

Will create a write permission for the user with internal ID = to the layer with internal ID = 58 of the collection with internal ID = . This means that he/she will be able to modify all site's properties inside the layer 58.

Revoking layer access

You need to do a POST to

With parameters:

    • {"layer_id"=>"58", "verb"=>"read", "access"=>"false" }

Or

    • {"layer_id"=>"58", "verb"=>"write", "access"=>"false"}

Removing a user from a collection

To delete a user's membership from a collection, do a DELETE to:

Setting site access

For setting access to all layers in an especific site to a user, you should do a POST to:

With parameters:

,

    "write"=>{       "all_sites"=>"false",        "some_sites"=>{         "0"=>{"id"=>"8376", "name"=>"Site 3"}}}}}

}}}

This means that the user with internal ID=1 will be able to see all properties of sites 3 and 4 (with internal IDs = 8376 and 11487) but will be only able to modify the Site 3's data.

Add a custom footer
Add a custom sidebar
Clone this wiki locally