Locations API

A Location is where source files are stored. Examples Location Kinds include Microsoft Azure Blob Store, Amazon S3, OpenStack Swift, and local or network attached storage.

A Location has a kind, a name, and a map of kind-specific configuration values. Each location is assigned a system-wide unique ID, which must be used when issuing harvesting requests.

Location Object

A Location Object describes a single storage location available for harvesting.

{
	"id": "{location_id}",
	"kind": "{kind}",
	"name": "{name}",
	"config": {
		"{configuration-key}": "{value}",
	"groups": [],
	"version": 0
	}
}

id - (string) System generated unique ID.
kind - (string) The location kind being added - must be present in the Supported Location Kinds API.
name - (string) A human-readable name for the location (e.g. “Post Production”).
config - (object) Key/value pairs of strings representing the configuration of the location.
- configuration-key - (string) The configuration key.
- configuration-value - (string) The configuration value.
groups - (array) Groups associated with this location (see Users and Groups API).
version - (int) Version number of location object. When a current version is updated, this value automatically increments by one (1).

The configuration object depends on the kind of location being connected to, for a complete breakdown, see the Supported Location Kinds API documentation.

Connecting to a location

To connect the GrayMeta Platform to a location, you add it using the following API call:

POST /api/data/v3/locations
{
	"kind": "{kind}",
	"name": "{name}",
	"config": {
		"{configuration-key}": "{value}"
	}
}

The system will set the version number to zero (0) and generate a unique ID for the location, which will be added to the object in the response:

{
	"id": "{location-id}",
	"kind": "{kind}",
	"name": "{name}",
	"config": {
		"{configuration-key}": "{value}",
	"groups": null,
	"version": 0
	}
}

location-id - (string) Unique ID representing the location.
version - (integer) value to track changes in the location object.

Bad configuration

When you add a location, the GrayMeta Platform immediately attempts to connect to it. If this fails, you will receive a non-2xx response, and a description of the error in the body.

Reading locations

To get a list of locations, you may make the following request:

GET /api/data/v3/locations

You will be given a location object with an array of locations:

{
	"locations": [
		{
			"id": "{location-id}",
			"kind": "{kind}",
			"name": "{name}",
			"config": {
				"{configuration-key}": "{value}"
			}
		},
		{
			"id": "{location-id}",
			"kind": "{kind}",
			"name": "{name}",
			"config": {
				"{configuration-key}": "{value}"
			}
		}
	]
}

Reading containers

To get a list of containers at a given location, see the Containers API documentation.

Reading a single location

If you know the ID of the location you wish to read, you can make the following request:

GET /api/data/v3/locations/{id}

{id} - (string) The location ID

The response will be a single location object:

{
	"id": "{location-id}",
	"kind": "{kind}",
	"name": "{name}",
	"config": {
		"{configuration-key}": "{value}",
	"groups": [],
	"version": 1
	}
}

Updating a location

You can post changes to a location by making the following request:

PUT /api/data/v3/locations/{id}
{
	"kind": "{kind}",
	"name": "{name}",
	"config": {
		"{configuration-key}": "{value}"
	},
	"version": 1
}

{id} - (string) The location ID

Note: The version in your request must match the current version.

The settings will be validated when the GrayMeta Platform attempts to connect to the location like it did when creating locations.

The response will be the updated location object with the version number incremented by one (1).

Deleting a location

While you can delete a location using the predictable RESTful approach, it is not recommended at this time.

Loadnstore Upload

Posting an asset to our loadnstore fileapi endpoint will create a file in our file_api location and kick off a harvest of the new file.

POST /files/loadnstore/{path_to_file}

Loadnstore Delete

Delete an item and all its artifacts (metadata.json, original asset, thumbnails…etc) from the mf2 platform. Quick note about the below, it requires you to send the same path that you used to upload the original asset.

DELETE /files/loadnstore/{path_to_file}

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.

Table of contents