Class Index

Classes


Intro

A Brief intro to the REST API V2
Defined in: Quick Start Guide.js.

Class Summary
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.

Class Detail
AAAAA()

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"
	   }
	 }
 ]

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Aug 06 2018 16:08:51 GMT-0500 (CDT)