Intro
A Brief intro to the REST API V2
Defined in: Quick Start Guide.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
AAAAA()
REST V2 Quick Start Guide Accepted Request Methods The MediaBeacon REST API accepts GET, POST and PUT requests interchangeably. |
REST V2 Quick Start Guide
Accepted Request Methods
The MediaBeacon REST API accepts GET, POST and PUT requests interchangeably. One thing to keep in mind when making a request is the parameter type and length. GET requests are limited to 2,048 characters and do not accept file parameters, so larger requests can only be performed by POST or PUT requests.
Encoding characters properly according to RFC 7230 and RFC 3986 is also important (at least when deployed with Tomcat at present, https://stackoverflow.com/questions/50361171/how-to-allow-character-in-urls-for-tomcat-8-5). If a 400 error occurs when using the bracket characters and tomcat, there are configuration changes you can make to allow those characters again (see above link, but the jist is to add relaxedQueryChars and relaxedPathChars parameters in the tomcat’s server.xml on teh connector elements, like:
<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="443" relaxedQueryChars='[]' relaxedPathChars='[]'/>
Authentication
There are three ways to authenticate with MediaBeacon when making a REST Call. The first is adding a username and a password to the request with the parameters user and pass. This is not a secure way to authenticate because the user's password will be in plain text, but it is a quick way to authenticate if you are running a request by hand.
The second way to authenticate is Basic Auth. Basic Auth is a standardized authentication process where the username and password are are encrypted together and added as a header to the request. The header should look something like this.
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
The most common way to authenticate is using an API key. API keys identify a single user in MediaBeacon. An API key can be generated by first logging into MediaBeacon with the user you want to associate with the key. Next navigate to Manage > System Status > API Keys. Near the bottom there is an option to Create API Key. This key can be used as a parameter in the url or the body of requests under the key name apikey.
/wf/restapi/v2/assets?apikey=978FFEF6-A668-4219-AA1D-268178B767E8&ids=[201629291]
Groups/ACLs
The REST API will run in a users default Group/ACL unless an ACL Id is specified. To specify an ACL Id, set the acl_id parameter to the desired Id. ACL Id’s can be collected by running the Groups endpoint.
/wf/restapi/v2/assets?apikey=978FFEF6-A668-4219-AA1D-268178B767E8&acl_id=0_6_19C23781-5F8A-459F-A98F-7A83031775D0&ids=[201629291]
Common Request Parameters
pretty
- true or false (default is false)
- If pretty is set to true the JSON response will be formatted with newlines and indentation.
- If pretty is false then the response will be more compact due to the lack of whitespace characters.
verbose
- true or false (default is false)
- If verbose is false or undefined the response will only contain a limited set of data.
- Assets only display id’s and directories their paths
- If verbose is true the response will contain a larger data set for each asset/directory
- name, path, height, width, bytes, …
Filters
- Filters allow users to restrict which results are returned in the response.
- Filtering can be done on the properties added by verbose.
- verbose needs to be set to true for filtering to occur
- Filters are only available for REST endpoints that collect data.
- ex. /wf/restapi/v2/delete doesn’t allow filtering. It will always return the assets/directories that it affected.
fields
- fields is an array of fieldId’s, or the namespace and field.
- ["http://purl.org/dc/elements/1.1/ title","http://purl.org/dc/elements/1.1/ subject"]
- Every asset that is returned by a REST endpoint will have the field values added to its object.
Usage Examples
A basic request with verbose, and fields not defined.
/wf/restapi/v2/assets
Parameters:
ids=[201629291,201629290]
Response:
[
{
"id": 201629291
},
{
"id": 201629290
}
]
A request for an asset with two field values.
/wf/restapi/v2/assets
Parameters:
ids=[201629291]
fields=["http://purl.org/dc/elements/1.1/ title","http://purl.org/dc/elements/1.1/ subject"]
Response:
[
{
"id": 201629291,
"fields": {
"http://purl.org/dc/elements/1.1/ title": "DC title field",
"http://purl.org/dc/elements/1.1/ subject": [
"check",
"1",
"2"
]
}
}
]
A request with verbose=true.
/wf/restapi/v2/assets
Parameters:
ids=[201629291]
verbose=true
Response:
[
{
"id": 201629291,
"name": "asset4.xmp",
"path": "RESTTest/assets/inner/asset4.xmp",
"height": 1,
"width": 1,
"bytes": 4096,
"lastModified": 1507813578000,
"mimeType": "application/octet-stream",
"previews": {
"thumbnail": "../servlet/jb.view?table=thumbnails&col=thumbnails&id=pe_323031363239323931",
"viewex": "../servlet/jb.view?table=viewex&col=viewex&id=pe_323031363239323931",
"downloadUrl": "../servlet/dload?id=201629291"
}
}
]
A request with verbose=true and fields.
/wf/restapi/v2/assets
Parameters:
ids=[201629291]
verbose=true
fields=["http://purl.org/dc/elements/1.1/ title","http://purl.org/dc/elements/1.1/ subject"]
Response:
[
{
"id": 201629291,
"name": "asset4.xmp",
"path": "RESTTest/assets/inner/asset4.xmp",
"height": 1,
"width": 1,
"bytes": 4096,
"lastModified": 1507813578000,
"mimeType": "application/octet-stream",
"previews": {
"thumbnail": "../servlet/jb.view?table=thumbnails&col=thumbnails&id=pe_323031363239323931",
"viewex": "../servlet/jb.view?table=viewex&col=viewex&id=pe_323031363239323931",
"downloadUrl": "../servlet/dload?id=201629291"
},
"fields": {
"http://purl.org/dc/elements/1.1/ title": "DC title field",
"http://purl.org/dc/elements/1.1/ subject": [
"check",
"1",
"2"
]
}
}
]
A request without filtering.
/wf/restapi/v2/directories
Parameters: none
Response:
[
all Directories...
]
A request filtering on name. This will return all directories where the name equals "test"
/wf/restapi/v2/directories
Parameters:
name=test
Response:
[
{
"name": "test",
"path": "test/folder/",
"resolver": "directory://182",
"assets": [
{
"id": 201628794
}
]
}
]
A request filtering on name. This will return all directories where the name starts with "test".
/wf/restapi/v2/directories
Parameters:
name=test*
Response:
[
{
"name": "test2",
"path": "test/test2/",
"resolver": "directory://256",
"assets": []
},
{
"name": "test",
"path": "test/",
"resolver": "directory://179",
"assets": [
{
"id": 201629305
}
]
}
]
A request filtering on name. This will return all directories where the name ends with "test2".
/wf/restapi/v2/directories
Parameters:
name=*test2
Response:
[
{
"name": "test2",
"path": "test/test2/",
"resolver": "directory://256",
"assets": []
},
{
"name": "test",
"path": "test/",
"resolver": "directory://179",
"assets": [
{
"id": 201629305
}
]
}
]
A request filtering on height equal to 1
/wf/restapi/v2/assets
Parameters:
ids=[201629291]
height=1
verbose=true
Response:
[
{
"id": 201629291,
"name": "asset4.xmp",
"path": "RESTTest/assets/inner/asset4.xmp",
"height": 1,
"width": 1,
"bytes": 4096,
"lastModified": 1507813578000,
"mimeType": "application/octet-stream",
"previews": {
"thumbnail": "../servlet/jb.view?table=thumbnails&col=thumbnails&id=pe_323031363239323931",
"viewex": "../servlet/jb.view?table=viewex&col=viewex&id=pe_323031363239323931",
"downloadUrl": "../servlet/dload?id=201629291"
}
}
]
A request filtering on bytes greater than 4095
/wf/restapi/v2/assets
Parameters:
ids=[201629291]
bytes=>4095
verbose=true
Response:
[
{
"id": 201629291,
"name": "asset4.xmp",
"path": "RESTTest/assets/inner/asset4.xmp",
"height": 1,
"width": 1,
"bytes": 4096,
"lastModified": 1507813578000,
"mimeType": "application/octet-stream",
"previews": {
"thumbnail": "../servlet/jb.view?table=thumbnails&col=thumbnails&id=pe_323031363239323931",
"viewex": "../servlet/jb.view?table=viewex&col=viewex&id=pe_323031363239323931",
"downloadUrl": "../servlet/dload?id=201629291"
}
}
]
A request filtering on bytes less than 4097
/wf/restapi/v2/assets
Parameters:
ids=[201629291]
bytes=<4097
verbose=true
Response:
[
{
"id": 201629291,
"name": "asset4.xmp",
"path": "RESTTest/assets/inner/asset4.xmp",
"height": 1,
"width": 1,
"bytes": 4096,
"lastModified": 1507813578000,
"mimeType": "application/octet-stream",
"previews": {
"thumbnail": "../servlet/jb.view?table=thumbnails&col=thumbnails&id=pe_323031363239323931",
"viewex": "../servlet/jb.view?table=viewex&col=viewex&id=pe_323031363239323931",
"downloadUrl": "../servlet/dload?id=201629291"
}
}
]