Home Page > Integration > REST API

REST API

Overview

This page describes the resources that make up the OpenAsset REST API (v1). We are continually improving the functionality of the API, but strive to retain backwards compatibility. 

 

HTTP Verbs

The following verbs are available unless otherwise specified.

 

HTTP Verb Description
HEAD When used against a resource, it will return only the HTTP header info. This is essentially a GET method with the body stripped.
GET Retrieve resources.
POST Creating new resources and/or performing actions. Please look at the Header section for additional info, in particular X-Ignored-Fields.
PUT Replacing and/or updating a resource. Please look at the Header section for additional info, in particular X-Ignored-Fields.
DELETE Deleting a resource.

 

 

Auth

In order to access restricted resources in the API you will need to provide your credentials (and have the correct permissions), the credentials should be encoded using Base64 from the following format username:password. This should then be included in the request header with the following syntax: Authorization: Basic <base64(username:password)>

 

 

Example

Using admin/admin as an example, the following is an example of how to access a resource with a user account:

 


curl -H "Authorization: Basic YWRtaW46YWRtaW4=" -X GET http://my.openasset.example.org/REST/1/Projects -D -

Or alternatively using curl's in built authentication functionality:


curl -u admin:admin -X GET http://my.openasset.example.org/REST/1/Projects -D -

 

 

Notes

It should be noted that access to the REST API is subject to the same restrictions found in the front end, this includes:

  • Approved IP range
  • Anonymous access is defaulted on (Please contact support to adjust this)

 

 

Data Types

The REST API documentation describes value types using the following data types as descriptions:

 

Name Description
string Alphanumeric characters, limits are specified if they are exceeded in a response error message. Default limit is 256 characters.
text Alphanumeric characters. Used to represent larger amounts of text. The default limit is 65535 characters. 
integer

Whole number.

boolean True represented by 1 and False represented by 0.
enum These are set values, usually strings. They will be described in greater detail when mentioned.
hash Generated by OpenAsset. This is a unique hash represented by a Hex string.
operator

Used to describe a search operator, these are:

  • OR
  • AND
datetime Datetime represented in the following format: YYYYMMDDhhmmss

 

 

Parameters

Many methods in the API, in particular GET requests, can take optional parameters which are passed using HTTP query string parameters. 

 

Parameter Value Type Usage Default
<field_name> <field_value_type> This will be explained in more detail for each verb. Essentially every field returned by the API is searchable as a parameter in the query. none
limit integer This is used to limit the amount of results returned by a query. 10
offset integer This is used to offset the results returned, i.e. offset=5 will show results starting from the 6th result (hiding the first 5). 0
textMatching string

Change the way in which text matching is performed. The options are:

  • contains
  • exact

​​ 

contains
orderBy string[,string]

Change the order in which results are returned. The direction can also be manipulated. Below is are some examples:

  • idDesc
  • ​id
  • idAsc
  • ​codeDesc

It's important to note that the direction is attached on to the end of the value and is case sensitive. This parameter can take multiple arguments.

none
displayFields string[,string] This parameter allows you to define which fields to return for your particular object. This is obviously Verb dependent.  none

 

 

Examples

Below are some example queries to help provide context. These examples use the Projects Noun.

1) Return 5 results with an offset of 5:


curl -X GET http://my.openasset.example.org/REST/1/Projects?limit=5&offset=5

2) Return 5 results with only the project code as a field:


curl -X GET http://my.openasset.example.org/REST/1/Projects?displayFields=code&limit=5

3) Return default number of results, ordered by id descending:


curl -X GET http://my.openasset.example.org/REST/1/Projects?orderBy=idDesc

 

 

Headers

The REST API employs several custom HTTP Headers to aid the user. These are described below.

 

Header Description
X-SessionKey Key used to persist a session across calls.
X-Full-Results-Count Number of total results in the system.
X-Display-Results-Count Number of results being returned.
X-Offset If the results are offset, this is the offset start point.
X-Timing Time taken to process the action.
X-Username Name of the user (if authenticated).
X-User-Id Id of the user (if authenticated).
X-OpenAsset-Version Version number of OpenAsset being called.
X-Ignored-Fields

These are fields that were ignored during a PUT or POST action; i.e. these fields have not been updated. 

 

 

Resources

The following are resources that are made available by the API.

 

Resource Verbs Endpoint Version Notes
AccessLevel GET /REST/1/AccessLevels/:id  
Albums GET/PUT/POST/DELETE /REST/1/Albums/:id PUT/POST/DELETE >= 8.1.11
AlternateStores GET /REST/1/AlternateStores/:id  
AspectRatios GET /REST/1/AspectRatios/:id  
Categories GET/PUT /REST/1/Categories/:id  
CopyrightHolders GET/PUT/POST /REST/1/CopyrightHolders/:id  
CopyrightPolicies GET/PUT/POST/DELETE /REST/1/CopyrightPolicies/:id  
Fields GET/PUT/POST/DELETE /REST/1/Fields/:id  
Files GET/PUT/POST/DELETE /REST/1/Files/:id  
Groups GET /REST/1/Groups/:id >= 8.1.11
Keywords GET/PUT/POST/DELETE /REST/1/Keywords/:id  
KeywordCategories GET/PUT/POST/DELETE /REST/1/KeywordCategories/:id  
Photographers GET/PUT/POST /REST/1/Photographers/:id  
Projects GET/PUT/POST/DELETE /REST/1/Projects/:id  
ProjectKeywords GET/PUT/POST/DELETE /REST/1/ProjectKeywords/:id  
ProjectKeywordCategories GET/PUT/POST/DELETE /REST/1/ProjectKeywordCategories/:id  
Searches GET/PUT/POST /REST/1/Searches/:id  
Sizes GET/PUT/POST/DELETE /REST/1/Sizes/:id  
TextRewrites GET /REST/1/TextRewrites/:id  
Users GET /REST/1/Users/:id  

 

 

Nested Resources

Some resources are nested, meaning that they can extend the functionality of an existing endpoint to provide additional information on a particular Object. These endpoints are outlined below.

Parent Expansions

Some nested resources can be retrieved in the parent noun with the use of expansions. These expansions can be fine tuned in what they return using the query parameter value. For example, you could retrieve all by using 'all' as the value. Or, you could use a comma delimited list of id's such as '1,2,3'.

If we wanted to have a list of the Files associated with an Album, we could make the following call which is a composite of the second example:

 

/REST/1/Albums/1?files=all

 

/REST/1/Albums/1 + /REST/1/Albums/1/Files

 

 

Resource Version Notes Expansion Name
 
Albums    
Nested Resource Verbs Endpoint    
Files GET/PUT/POST/DELETE /REST/1/Albums/:id/Files >= 8.1.11 files
Groups GET/PUT /REST/1/Albums/:id/Groups >= 8.1.11 groups
Users GET/PUT /REST/1/Albums/:id/Users >= 8.1.11 users
 
Files    
Nested Resource Verbs Endpoint    
Fields GET/PUT /REST/1/Files/:id/Fields PUT >= 8.1.11 fields
Keywords GET/PUT/POST/DELETE /REST/1/Files/:id/Keywords POST/DELETE >= 8.1.11 keywords
Sizes GET /REST/1/Files/:id/Sizes   sizes
 
Projects    
Nested Resource Verbs Endpoint    
ProjectKeywords GET/PUT/POST/DELETE /REST/1/Projects/:id/ProjectKeywords POST/DELETE >= 8.1.11 projectKeywords
Fields GET/PUT /REST/1/Projects/:id/Fields PUT >= 8.1.11 fields
 
Fields    
Nested Resource Verbs Endpoint    
FieldLookupStrings GET /REST/1/Fields/:id/FieldLookupStrings   fieldLookupStrings
 
Searches    
Nested Resource Verbs Endpoint    
Groups GET/PUT /REST/1/Searches/:id/Groups >= 8.1.11 groups
Results GET/POST /REST/1/Searches/:id/Results   results
Users GET/PUT /REST/1/Searches/:id/Users >= 8.1.11 users

Postman Configuration

We have created a Postman configuration that can be used during development against your own REST API environment.

 

From 8.1.11 use the following configuration:


https://www.getpostman.com/collections/4134d81f4835c87ad9d7

 

Errors

The API returns a variety of errors.

 

Access a non existent Verb


curl -X GET http://my.openasset.example.org/REST/1/Pprojects -D -

Will result in the following response:


HTTP/1.1 404 Not Found
{
   "error_message" : "Cannot create requested REST module /REST/1/Pprojects",
   "http_status_code" : "404"
}

 

Permission issues


curl -X POST http://my.openasset.example.org/REST/1/Projects -D -

Will result in the following response:


HTTP/1.1 403 Forbidden

{
   "error_message" : "Access denied to POST Projects",
   "http_status_code" : "403"
}

 

No JSON in POST Body


curl -u admin:admin -X POST http://my.openasset.example.org/REST/1/Projects -D -

Will result in the following response:


HTTP/1.1 400 Bad Request

{
"error_message" : "No JSON body provided for POST request",
    "http_status_code" : "400"   
}


Requested object not found


curl -u admin:admin \
  -X PUT \
  ​http://my.openasset.example.org/REST/1/Projects/1 \
  ​-D - \
  ​-d '{"alive": 0}'

Will result in the following response:


HTTP/1.1 404 Not Found

{
   "error_message" : "Requested object not found",
   "http_status_code" : "404"
}

 

Changelog

 

Description OpenAsset Version
   
Last modified
06:39, 27 Apr 2017

Tags

Classifications

This page has no classifications.