Batch API

Introduction

This document details the end points related to the batch management of the OBM provisioning system.

The default exchange format is JSON.

Namings

In this document we take /provisioning/{apiVersion}/{domainUUID} as the base URI of REST end points. It will be called {baseURI} in the document. The notation {serverBaseURL} represents the root URL of the REST server, eg http://1.2.3.4:8080/ The notation {batchId} represents a unique batch number. The notation {batchStatus} represents a batch status, issued from the batch status list. The notation {apiVersion} represents a string linking to the version of the API that the client want to use (eg. "v1")

Durability

The batches are stored in the database. The batches in "ERROR" and "DONE" states are purged from the database once a day. Only the 200 last batches are kept.

Start of a batch

Definition

This end point creates a new batch.

REST information

• method: POST
• uri: {baseURI}/batches
• query string arguments: none
• return code: 201 Created on success, 5XX errors on errors

• return HTTP header:

  Location: {baseURI}/batches/{batchId}
  

• return content: On success:

  {
    id: {batchId}
  }
  

On error: see "standard errors"

Commit of the batch

Definition

This end point starts the process responsible of applying the operations added to the batch.

Only the first call to this end point is taken into account. Subsequent calls to this end point are ignored.

It should be possible for two batches to run in parallel, however some operations needs to be hold until the end of all batches, and being done only once. Those operations are:

• postfix maps regeneration

REST information

• method: PUT
• uri: {baseURI}/batches/{batchId}
• query string arguments: none
• return code: 200 on success, 5XX errors on errors, 404 on a non existing {batchId}

• return content: On success:

  {
    id: {batchId}
  }
  

On error: see "standard errors"

Discard of the batch

Definition

This end point forgets the batch: it removes all operations recorded inside this batch, and invalidates the {batchId}.

This end point can't be called after the batch has been commited.

REST information

• method: DELETE
• endpoint: {baseURI}/batches/{batchId}
• query string arguments: none
• return code: 200 on success, 5XX errors on errors, 404 on a non existing {batchId}

• return content: On success:

  {
    id: {batchId}
  }
  

On error: see "standard errors"

Status of the batch

Definition

The objective of this end point is to get the actual state of the batch, and associated informations.

REST information

• method: GET
• endpoint: {baseURI}/batches/{batchId}
• query string arguments: none
• return code: 200 on success, 5XX errors on errors, 404 on a non existing {batchId}
• return content: On success: the "batch status data structure"

On error: see "standard errors"

batch status list

ERROR: the batch is in an error state IDLE: the batch is created RUNNING: the batch has been commited and is actually applying the operations DONE: the batch has been commited and has finished running.

batch status data structure

{
  id: {batchId},
  // current status, one of the "batch status list"
  status: STRING,
  // the number of operations in this batch
  operationCount: NUMBER,
  // the number of operations that are done
  operationDone: NUMBER,
  // the result, per operation
  // ordering follows the registration of the operations
  // ie. first registered operation's result will be at index 0 of this array
  operationStatus: [
    // one successfull operation
    {
      entity_type: "user"|"group",
      entity: {/* entity description in JSON */},
      operation: "POST"|"PUT"|"DELETE"|"PATCH",
      status: STRING, // current status, one of the "batch status list"
    },
    // one failed operation
    {
      entity_type: "user"|"group",
      entity: {/* entity description in JSON */},
      operation: "POST"|"PUT"|"DELETE"|"PATCH",
      status: STRING, // current status, one of the "batch status list"
      error: "Unable to delete UserObm(id=42). The database is unreachable."
    },
    ...
  ]
}

New Arrivals