Appspace Graph API
Introduction
Building an extension requires a developer to leverage the Appspace Graph API to call methods that make changes to resources within an Appspace account. The Appspace Graph API is accessible over a HTTP based REST protocol.
Resource URI
The request URI defines the resource to access in the Appspace Graph API. Each resource has a unique URI. The request URI is described by the following structure:
http://{Appspace Server IP or URL}/api/{api version}/{extension}/{resource path}
- Appspace Server IP – The IP address (IPV4) or URL of the Appspace sever instance.
- API Version – The version of the API exposed by the Appspace instance.
- Extension – The name of the core extension in the Appspace Graph API.
- Resource – A path to the resource.
For example, the following URI is used to access the contents in the Library.
http://{server IP}/api/v1/appspace/library/contents
API Operations
RESTful architecture defines that users operate on a resource by altering the state of the resource. In the Appspace Graph API this is achieved using the HTTP methods, GET, POST, PUT, and DELETE. Users must specify the HTTP method in their requests to define the action to perform on the resource in the Appspace Graph. The following list explains the details of each method.
- POST – Creates a new entity in the Appspace Graph. This method adds a new object into the Appspace Graph.
- GET – Retrieves data about the resource. This method does not alter the resource.
- PUT – Updates the details of an existing resource. This method alters details of existing objects in the Appspace Graph.
- DELETE – Deletes a resource. This method removes objects from the Appspace Graph.
Data Format
The Appspace Graph API allows requests and responses to communicate using either JSON data formats or XML data formats. Developers need to define the data format used when sending a request using the “Content-Type” HTTP header. Developers can define the data format used to receive the response using the “Accept” HTTP header.
To use JSON data format:
content-type : application/json
accept : application/json
To use XML data format
content-type : application/xml
accept : application/xml
Security Token
All calls to the Appspace Graph API must be authenticated by way of passing a security token in the request. When an extension is in operation, the Appspace Core Framework will pass in the following parameters to the extension via a querystring.
- Parameter key: t
- Value Type: 32 digit hexadecimal number
- Description: The security token of the current logged in user. Extensions will use this to make API calls to the Appspace Graph.
Extension authors must retrieve the token value from the querystring, and add the token into the request header as follows:
Response Status
Every response from the Appspace Graph API will include a status code to identify the state of the operations. The following table details the details of the return status codes.
- Code Value 0 – None
- Code Value 1 – Success
- Code Value 2 – Failure
- Code Value 3 – Unchanged
Putting It Together
The following illustrates the general structure of a HTTP message utilizing the Appspace Graph API.
POST http://preview.nexusondemand.com/api/v1/token/request HTTP/1.1
Content-type: application/JSON
Host: preview.nexusondemand.com
Content-Length: 85
Connection: Keep-Alive
{"Authentication":{"Username":"admin","Password":"password123","SecurityToken":null}}
There are a number of tools freely available to use to test method calls to the Appspace Graph API. One example is Dev HTTP Client (Google Chrome Application from here).
The following demonstrates the steps to use the tool to construct HTTP messages to the Appspace Graph API.
