AMEE API / API Operations

This page abstractly describes the API operations available in the AMEE API. Specific API operations for the AMEE API are detailed on other pages.

All API operations are subject to varying levels of authentication and authorization. Where relevant, details on authorization roles are detailed here. It's worth looking at AMEE concepts and the URL architecture when reading this page.

Overview

All resources in AMEE are available via the AMEE API and can be retrieved via friendly  RESTian style URLs. The standard HTTP methods (GET, POST, PUT and DELETE) are used to manipulate AMEE resources.

Many resources within AMEE are identified by a unique ID (UID). These UIDs will be returned in API responses and can be supplied in subsequent API calls.

Fetching resources (GET method)

All resources are fetched using the HTTP GET method. Resources are organised in a hierarchical URL structure following RESTian conventions. A resource is one of the key AMEE objects, a collection of these objects or some other view onto AMEE data or functionality.

Resources cannot be manipulated by the GET method alone. The other HTTP methods are used to create, modify and delete resources.

Depending on the resource fetched, further resources may also be fetched at a deeper level in the URL hierarchy. All resources contain information required to navigate up, down and across the URL hierarchy where relevant.

As an example, a Data Category resource will consist of other Data Categories, Data Items, etc. After fetching a Data Category resource it will be possible to navigate to child resources deeper down in the URL hierarchy based on the information returned.

Resources are not 100% guaranteed to always be present at the URL they were originally published under. Each API session should iterate through the URL structure and derive resource URLs from other calls within that session.

It is the responsibility of the client to determine URLs by understanding data returned from less detailed API calls and applying this by following the URL architecture.

Creating new resources (POST method)

Resources are created using the HTTP POST method. Most resources can only be created by POSTing to parent resources. For instance, if you are adding a new Profile Item it needs to be posted to the parent Profile Category.

Each resource supporting the POST method has a defined set of accepted parameters, such as ‘name’ and ‘value’. After POSTing a new resource it will become available at a new predictable URL conforming to the URL conventions in this wiki.

POST calls will result in relevant HTTP status codes. Some post calls will result in a limited XML or JSON response.

Modifying resources (PUT method)

Resources can be modified using the HTTP PUT method. Not all resources are modifiable and resources can only be modified when authorized.

Resources are modified directly with a PUT call to their unique URLs. Each resource supporting the PUT method has a defined set of accepted parameters, such as ‘name’ and ‘value’.

Some resources may be modified by other processes and API calls to other resources. For instance, if a Data Item representing a core CO2 value is modified the value of dependant items, such as Profile Items, may also be changed.

PUT calls will result in relevant HTTP status codes. Some put calls will result in a limited XML or JSON response.

Deleting resources (DELETE method)

Resources can be deleted using the HTTP delete method to their unique URL. Not all resources can be deleted and resources can only be deleted when authorized.

When deleting a resource all dependent resources are also deleted and other related resources may also be modified. For example, if you delete a Profile Item all associated Profile Item Values will also be deleted.

DELETE calls will result in relevant HTTP status codes.