Getting Started

Overview

The CEERN API hosts a collection of conservation/education resources submitted by a large range of contributors. Contributers will have the ability to rate, collect and republish resources from any other source on the network.

Structurally, there are three entities that the API models.

• Resource - A resource is the main entity. A resource can have many different attributes associated with it, including a time (for events), a location, files, and a description. Resources can also be categorized by their topic, target audience, or by keyword.
• User - A user can contribute resources to the API. Users have contact info associated with them, including address, email, phone, and organization information.
• Source - A source owns a set of users. When you register for an API key, you are signing up as a source. Source's will have basic contact info (URL and email) associated with them.

Resources are fairly generic, and can be anything from a handout to an event. Structurally, they should have a name, description, target audience, an owner (the user) and additional information that can either live as a file in the API or a link elsewhere. If the resource is an event, it should also have a time and location component.

The REST Server

The REST interface is located at http://api.resourcecommons.org/services/rest [Please note that an API call to this particular page will not return anything] For more on REST web services in general, check out Wikipedia's article on REST Services.

Our particular REST implementation allows for a variety of return formats. By default, the CEERN API data is returned in XML format, but data can returned in the following formats by adding the proper extension to the end of the URL.

• .xml - XML
• .jsonp - JSON (Be sure to add a javascript function callback in your call)
• .php - Serialized PHP
• .yaml - YAML

EXAMPLE: Javascript example

EXAMPLE: PHP simple example

Authentication

Authentication is handled through the set of public/private keys you received upon registering to use the CEERN API. If you make a call that requires authentication, you need the following items:

timestamp

A UNIX timestamp corresponding to when you sent the call.

nonce

A unique string. A new string must be generated for each call.

public_key

The public key associated with your API login.

private_key

The private key associated with your API login.

The first three items above ( timestamp, nonce, public_key) are used as parameters to generate an SHA-256 HMAC hash. The hash is seeded with the private key.

Generating the Hash

  $hash_parameters = array($timestamp, $public_key, $nonce);
  $hash = hash_hmac("sha256", implode(';', $hash_parameters), $private_key);
  

On your call to the server, send along the following information as parameters:

timestamp

A UNIX timestamp corresponding to when you sent the call.

nonce

A unique string. A new string must be generated for each call.

public_key

The public key .

hash

The hash described above.

Calling the Server

  $ceen_posturl = sprintf('http://api.resourcecommons.org/user.php?hash=%s
×tamp=%s&public_key=%s&nonce=%s', $hash, $timestamp, $public_key, $nonce);

Not all calls require authentication, but will not fail if authentication credentials are sent to them.

EXAMPLE: An authenticated call example with hash generation and posted data.

A Note on Resource Names

A resource name is a required hash parameter for authenticated calls.

Currently, resource names are generated by the following pattern.

[resource name]_resource.[function call]

The function call either corresponds to it's CRUD name (create, retrieve, update, delete, index), or is the last segment of the url.