Batches

Batch

A batch represents a submitted job of assets. Collections of batches are returned from:

/customers/{customer}/queue/batches
/customers/{customer}/queue/active
/customers/{customer}/queue/recent

Typically you’d interact with a batch while it is being processed, or to update your internal systems with the status of assets on the platform. The data in a batch can be used to generate progress bars and other reporting information in your systems.

Old batches are kept on the platform for at least a year but are eventually archived.

{
    "@context": "https://dlcs.github.io/vocab/context/future.json",
    "@id": "https://api.dlcs.example/customers/2/queue/batches/875629",
    "@type": "vocab:Batch",
    "submitted": "2023-09-02T10:32:49.9404910Z",
    "count": 90,
    "completed": 90,
    "finished": "2023-09-02T10:45:17.4325100Z",
    "errors": 0,
    "superseded": false,
    "images": "https://api.dlcs.example/customers/2/queue/batches/875629/images",
    "assets": "https://api.dlcs.example/customers/2/queue/batches/875629/assets",
    "test": "https://api.dlcs.example/customers/2/queue/batches/875629/test"
}

/customers/{customer}/queue/batches/{batch}

Method	Label	Expects	Returns	Status
GET	Retrieve a Batch	-	vocab:Batch	200 OK, 404 Not Found

💻 Batch operations GET a batch, its images, its assets, and POST to its test endpoint

submitted

The date and time the batch was created by the platform in response to receiving a collection of assets POSTed to the queue.

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

count

The number of assets in the batch. The platform imposes a limit on the size of collections that can be submitted to a queue, therefore a batch cannot have a count greater than this.

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

completed

The number of assets in the batch that have completed processing (whether or not they all succeeded).

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

errors

The number of assets in the batch that failed processing. Errored assets still count towards completed — a batch whose errors is greater than zero can therefore finish with completed equal to count.

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

finished

The date and time the batch was finished processing. This will be absent if the batch is waiting to be processed or is still being processed. A finished batch may contain errors.

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

superseded

Has this batch been superseded by another? An asset can only be processed by one active batch at a time. The batch property of an asset points to the most recent batch the asset was a part of. If no assets are associated with this batch, then it has been superseded by one or more later batches. The platform does not update this property automatically; POSTing to the test resource of a batch brings it (and the batch’s other bookkeeping fields) up to date.

See the images and assets properties below for further information.

domain	range	readonly	writeonly
vocab:Batch	xsd:boolean	True	False

images

A link to a Collection of all the assets currently in the batch, defined as all the assets that have this batch as their batch property at time of request.

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

/customers/{customer}/queue/batches/{batchId}/images

This collection supports asset query parameters.

Method	Label	Expects	Returns	Status
GET	Retrieves all assets for which this is the most recent batch	-	hydra:Collection	200 OK

An asset can only be associated with one batch. This means that if an asset is included in a subsequent batch, it will no longer be a member of this batch’s images. If a batch has “lost” all of its assets in this way, it is said to be superseded.

assets

A link to a Collection of all the assets in the batch at the point the batch was created, as long as they are still present in the system and have not been deleted. Many batches can include the same asset in this property, whereas only one batch can include an asset in its images property.

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

/customers/{customer}/queue/batches/{batchId}/assets

This collection supports asset query parameters.

Method	Label	Expects	Returns	Status
GET	Retrieves all assets specified by the batch at creation time	-	hydra:Collection	200 OK

test

An HTTP POST to this resource makes the platform re-examine the batch against the current state of its assets, and correct the batch where the two have drifted apart. Testing a batch can make three kinds of correction:

If none of the batch’s assets still belong to it (they have all since been submitted in later batches), superseded is set to true.
If every asset in the batch has completed processing but the batch has no finished date, finished is set.
If the batch is complete but its count, errors and completed values disagree with the actual assets, the counts are recalculated.

/customers/{customer}/queue/batches/{batchId}/test

Method	Label	Expects	Returns	Status
POST	Force reconciliation of the batch’s superseded, finished and count fields.	-	JSON object with single success property (boolean).	200 OK, 404 Not Found

The response body is a plain JSON object, not a Hydra resource — a deliberate exception for this action endpoint:

{ "success": true }

success is true if testing the batch made any of the corrections above, and false if the batch was already up to date — it does not indicate failure.

success is true when the test resulted in an update to the batch (marking it superseded and/or finished), and false when the batch was tested but no changes were needed. Either way the test itself succeeded — false is not an error.

Adjunct Batch

An adjunct batch represents a submitted job of adjuncts. Collections of adjunct batches are returned from:

/customers/{customer}/adjunctQueue/batches
/customers/{customer}/adjunctQueue/active
/customers/{customer}/adjunctQueue/recent

Typically you’d interact with a batch while it is being processed, or to update your internal systems with the status of adjuncts on the platform. The data in a batch can be used to generate progress bars and other reporting information in your systems.

Old batches are kept on the platform for at least a year but are eventually archived.

{
    "@context": "https://dlcs.github.io/vocab/context/future.json",
    "@id": "https://api.dlcs.example/customers/2/adjunctQueue/batches/875629",
    "@type": "vocab:AdjunctBatch",
    "submitted": "2023-09-02T10:32:49.9404910Z",
    "count": 90,
    "completed": 90,
    "finished": "2023-09-02T10:45:17.4325100Z",
    "errors": 0,
    "currentAdjuncts": "https://api.dlcs.example/customers/2/adjunctQueue/batches/875629/current",
    "adjuncts": "https://api.dlcs.example/customers/2/adjunctQueue/batches/875629/adjuncts"
}

/customers/{customer}/adjunctQueue/batches/{batch}

Method	Label	Expects	Returns	Status
GET	Retrieve a Batch	-	vocab:AdjunctBatch	200 OK, 404 Not Found

💻 Batch operations GET an adjunct batch, its currentAdjuncts, and its adjuncts

submitted

The date and time the batch was created by the platform in response to receiving a collection of adjuncts POSTed to the queue.

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

count

The number of adjuncts in the batch. The platform imposes a limit on the size of collections that can be submitted to a queue, therefore a batch cannot have a count greater than this.

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

completed

The number of adjuncts in the batch that have completed processing (whether or not they all succeeded).

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

finished

The date and time the batch was finished processing. This will be absent if the batch is waiting to be processed or is still being processed. A finished batch may contain errors.

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

currentAdjuncts

A link to a Collection of all the adjuncts currently in the batch, defined as all the adjuncts that have this batch as their batch property at time of request.

domain	range	readonly	writeonly
vocab:AdjunctBatch	🔗 hydra:Collection (of vocab:Adjunct)	True	False

/customers/{customer}/adjunctQueue/batches/{batchId}/current

Method	Label	Expects	Returns	Status
GET	Retrieves all adjuncts for which this is the most recent batch	-	hydra:Collection	200 OK

An adjunct can only be associated with one current batch. This means that if an adjunct is included in a subsequent batch, it will no longer be a member of this batch’s currentAdjuncts.

adjuncts

A link to a Collection of all the adjuncts in the batch at the point the batch was created, as long as they are still present in the system and have not been deleted. Many batches can include the same adjunct in this property, whereas only one batch can include an adjunct in its currentAdjuncts property.

domain	range	readonly	writeonly
vocab:AdjunctBatch	🔗 hydra:Collection (of vocab:Adjunct)	True	False

/customers/{customer}/adjunctQueue/batches/{batchId}/adjuncts

Method	Label	Expects	Returns	Status
GET	Retrieves all adjuncts specified by the batch at creation time	-	hydra:Collection	200 OK