Space

Spaces allow you to partition assets into groups. You can use them to organise your assets logically, like folders. You can also define different default settings to apply to assets when they are registered in a Space - for example, default delivery channels. These can be overridden for individual assets. There is no limit to the number of assets you can register in a space.

{
    "@context": "https://dlcs.github.io/vocab/context/future.json",
    "@id": "https://api.dlcs.example/customers/2/spaces/99",
    "@type": "vocab:Space",
    "id": 36,
    "name": "An example space",
    "created": "2022-08-11T13:00:32.2635950Z",
    "approximateNumberOfImages": 4,
    "images": "https://api.dlcs.example/customers/2/spaces/99/images",
    "defaultDeliveryChannels": "https://api.dlcs.example/customers/2/spaces/99/defaultDeliveryChannels",
    "defaultRoles": [ "https://api.dlcs.example/customers/2/roles/clickthrough" ],
    "defaultTags": [ "green", "red" ],
    "storage": "https://api.dlcs.example/customers/2/spaces/99/storage"
}

/customers/{customer}/spaces/{spaceId}

Method	Label	Expects	Returns	Status
GET	Retrieve a Space	-	vocab:Space	200 OK, 404 Not Found
PUT	Create or update a space. PUT allows you to specify the integer space ID	vocab:Space	vocab:Space	200 OK, 201 Created, 400 Bad request, 409 Conflict
PATCH	Modify one or more fields of a space.	vocab:Space	vocab:Space	200 OK, 400 Bad request, 404 Not found, 409 Conflict
DELETE	Delete a space. If the space is not empty, the response is 409 Conflict.	-	-	204 No Content, 404 Not found, 409 Conflict

💻 Space operations HTTP operations directly on a Space

id

The model id or integer identifier of a space. This is provided for read convenience, you can’t set it yourself. When creating a new Space, the platform will assign the next available integer id when you POST to customer.spaces, or you can PUT to a particular space URL, e.g.,

PUT /customers/2/spaces/3333
{
    "name": "My space with all the 3s",
}

domain	range	readonly	writeonly
vocab:Space	xsd:integer	True	False

name

A friendly name for the space. This is for your use in the portal (like a folder name) - it doesn’t get displayed to users.

domain	range	readonly	writeonly
vocab:Space	xsd:string	False	False

created

Date the space was created.

domain	range	readonly	writeonly
vocab:Space	xsd:dateTime	True	False

approximateNumberOfImages

The number of assets (not just images) in the space. This figure may not be accurate while you are adding assets but will eventually become accurate.

domain	range	readonly	writeonly
vocab:Space	xsd:integer	True	False

images

All the assets (not just images) in the Space. This is presented as a Hydra Collection of assets, and can take any asset query to filter the returned collection. You can also adjust the page size to suit your application needs (the default is 100).

domain	range	readonly	writeonly
vocab:Space	🔗 hydra:Collection (of vocab:Image)	True	False

/customers/{customer}/spaces/{spaceId}/images

Method	Label	Expects	Returns	Status
GET	(with optional query parameter).	-	hydra:Collection	200 OK
PATCH	Update one or more assets	🔗 hydra:Collection (of vocab:Image)	🔗 hydra:Collection (of vocab:Image)	200 OK, 400 Bad Request

The PATCH operation performs a bulk update of assets in the space. The body is a Hydra Collection whose member array contains the assets to update; each member must include its id, and the same id may not appear twice. There is a maximum number of assets in a single call (250 by default; deployments can configure this).

The PATCH operation is only permitted for changes to assets that do not require reprocessing, because it updates the submitted assets synchronously. Therefore changes to metadata fields like string1, tags or roles can be patched, but changes to fields like origin, maxWidth or deliveryChannels are rejected with 400 Bad Request. Assets are updated one at a time: if an update fails partway through, changes already applied to earlier members are not rolled back.

💻 Space.images operations HTTP operations on the images collection of a Space, including bulk PATCH

defaultDeliveryChannels

A link to a paged Collection of default Delivery Channels. These are only used when you register an asset without supplying any delivery channels on the submitted asset resource. The platform uses the mediaType of the asset to match one of these. It looks in the defaultDeliveryChannels property of the asset’s Space first, and continues looking at this customer level if none match from those in the space.

domain	range	readonly	writeonly
vocab:Space	🔗 hydra:Collection (of vocab:DeliveryChannel)	True	False

Unlike delivery channels on assets, any delivery channels listed here MUST have the mediaType property, which is used by the platform to match them to an asset. See Delivery Channels.

HTTP operations

/customers/{customer}/spaces/{space}/defaultDeliveryChannels

Method	Label	Expects	Returns	Status
GET	List all your default Delivery Channels	-	A paged hydra:Collection of vocab:DeliveryChannel	200 OK
POST	Add a new default Delivery Channel. The body must include the mediaType property. The platform will create a GUID for the last path element, which you can use on PUT and DELETE operations.	-	vocab:DeliveryChannel	201 Created

See also the PUT and DELETE operations on DeliveryChannel.

NB this is not a collection of collections like deliveryChannelPolicies.

defaultRoles

An array of strings where the strings are URIs of Roles defined under customer.roles.

These are the default Roles for assets in this space.

Caution

This property is not currently applied. The intended behaviour - an asset registered without its own roles property is given all of the roles in defaultRoles, while an asset registered with an explicit empty array is not - is not implemented in the current platform. Values you set here are stored and returned, but have no effect on assets. Whether this behaviour will be implemented or the property retired is tracked in protagonist #1253.

domain	range	readonly	writeonly
vocab:Space	Array of xsd:string	False	False

💻 Space default roles Setting the default roles for a Space by patching the Space

defaultTags

An array of string tags.

Caution

This property is not currently applied. The intended behaviour - an asset added to the space is given these tags unless registered with at least one tag of its own - is not implemented in the current platform. Values you set here are stored and returned, but have no effect on assets. Whether this behaviour will be implemented or the property retired is tracked in protagonist #1253.

The tags can be any string. You can use tags (set directly on assets) in API asset queries and in named queries.

domain	range	readonly	writeonly
vocab:Space	Array of xsd:string	False	False

💻 Space operations The Patch example updates the defaultTags

storage

Returns information about storage usage for the customer within this Space. See the StoragePolicy topic for more information.

domain	range	readonly	writeonly
vocab:Space	vocab:CustomerStorage	True	False

HTTP operations

/customers/{customer}/spaces/{space}/storage

Method	Label	Expects	Returns	Status
GET	Returns the storage resource for this space	-	vocab:CustomerStorage	200 OK

💻 Space storage Retrieving a storage report for a space