Batch Job Service RESTful APIs

Brief Description

Error rendering macro 'excerpt-include' : No link could be created for 'Batch Job Service Description and Assumptions'.
For a full description, visit the Service Description and Assumptions page.

Assumptions

For a complete list of assumptions, visit the Service Description and Assumptions page.

References

Batch Processing User Story Summary
Batch Job Service Description and Assumptions
Batch Job Schema

REST-based API

The Batch Job Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual Batch Job instances, plus list operations on multiple Batch Job instances. These follow the Common model for CollectionSpace REST services.

Batch Job CRUD+L services

Create a Batch Job

Creates a new Batch Job record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Batch Job record. Follows standard Create model. See the documentation of the Batch Job schema, below. Example:

POST /cspace-services/batch HTTP/1.1
Read a Batch Job

Reads an existing Batch Job record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Batch Job schema, below. Example:

GET /cspace-services/batch/{id} HTTP/1.1
Update a Batch Job

Updates an existing Batch Job record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Batch Job schema, below. Example:

PUT /cspace-services/batch/{id} HTTP/1.1
Delete a Batch Job

Deletes an existing Batch Job record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

DELETE /cspace-services/batch/{id} HTTP/1.1
List Batch Job instances

Lists existing Batch Job records, with summary information for each. Follows standard List model. See the documentation of the Batch Job list schema, below. Example:

GET /cspace-services/batch/ HTTP/1.1

In addition to the standard paging params, batch jobs can be filtered for an invocation context, by specifying the document type and the invocation mode (both must be specified together):

  • doctype={document type name, e.g., CollectionObject, Intake, etc.}
  • inv={single, list, group}

For example, to get the batch jobs that can be invoked with a list of CollectionObjects:

GET /cspace-services/batch?doctype=CollectionObject&inv=list HTTP/1.1

Batch Job Invocation services

Batch jobs are invoked using nearly the same REST API call - and identical payload schemas - to those used to invoke the Reporting service. For details, see Reporting Invocation services, substituting batch for reports in the URI in the POST example.

For the current schema for the payload used to invoke batch jobs and reports, see:

Batch Job REST payload schemas

Batch Job instance schema

The schemas below are illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Batch Job records, please see the Batch Job record schema for the current release.

Create and Update should use the following schema:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="batch">
  <ns2:batch_common xmlns:ns2="http://collectionspace.org/services/batch"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <supportsDocList>true</supportsDocList>
    <forDocTypes>
      <forDocType>CollectionObject</forDocType>
    </forDocTypes>
    <name>TestCreateAndLinkLoanOutBatchJob</name>
    <className>org.collectionspace.services.batch.nuxeo.CreateAndLinkLoanOutBatchJob</className>
    <supportsSingleDoc>true</supportsSingleDoc>
    <createsNewFocus>true</createsNewFocus>
    <notes>This should be interesting</notes>
  </ns2:batch_common>
</document>

Batch Job list schema

Batch Job uses the new abstract common list mechanism, allowing for some configuration of returned fields. By default, List (and variants) will return the following schema. This schema includes the uri and csid fields to help facilitate access to individual records:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:abstract-common-list xmlns:ns2="http://collectionspace.org/services/jaxb">
  <pageNum>0</pageNum>
  <pageSize>40</pageSize>
  <itemsInPage>1</itemsInPage>
  <totalItems>1</totalItems>
  <fieldsReturned>name|forDocType|uri|csid</fieldsReturned>
  <list-item>
    <csid>05e5c5cf-faad-427c-8220</csid>
    <uri>/batch/05e5c5cf-faad-427c-8220</uri>
    <name>TestCreateAndLinkLoanOutBatchJob</name>
    <forDocType>CollectionObject</forDocType>
  </list-item>
</ns2:abstract-common-list>