Batches API
===========

=============
Batch Methods
=============

Batches are groups of compute jobs that share a common hardware configuration and run in parallel.


.. http:get:: /batches

    List all the available batches for the user

    :reqheader Authorization: API key or Bearer token for user authentication
    :status 200: Success. Returns a list of batch id's and associated properties.
    :status 500: Unknown error occurred during processing.

    **Response Syntax**:

    A list of Batch objects.

    .. sourcecode:: json

     [
       {
         "batch_id": "string",
         "batch_tool": {
           "tool_id": "string",
           "tool_name": "string",
           "tool_description": "string"
         },
         "n_jobs": 123,
         "hardware": {
           "filesystem_list": [
             {
               "filesystem_id": "string",
               "filesystem_name": "string"
             }
           ],
           "cpu": 123,
           "memory": 123
         }
       }
     ]

    :raises: May raise exceptions related to database operations or service availability.


.. http:delete:: /batches

    Deletes all the available batches and jobs for the user

    :reqheader Authorization: API key or Bearer token for user authentication
    :status 200: Success. No return text.
    :status 500: Unknown error occurred during processing.

    :raises: May raise exceptions related to database operations or service availability.


.. http:get:: /batches/<batch_id>

    Returns attributes for batch

    :reqheader Authorization: API key or Bearer token for user authentication
    :status 200: Success. Returns a list of batch id's and associated properties.
    :status 500: Unknown error occurred during processing.

    **Response Syntax**:

    A BatchStatus object.

    .. sourcecode:: json

     {
       "submitted": 123, 
       "pending": 123, 
       "runnable": 123, 
       "starting": 123,
       "running": 123, 
       "succeeded": 123,
       "failed": 123
     }

    :raises: May raise exceptions related to database operations or service availability.

.. http:get:: /batches/<batch_id>

    Deletes the specified batch.

    :reqheader Authorization: API key or Bearer token for user authentication
    :status 200: Success. No return text.
    :status 500: Unknown error occurred during processing.

    :raises: May raise exceptions related to database operations or service availability.

===========
Job Methods
===========

Jobs are individual compute tasks. They are child resources of batches.


.. http:get:: /batches/<batch_id>/jobs

    List all the available jobs in the batch.

    :reqheader Authorization: API key or Bearer token for user authentication
    :status 200: Success. Returns a list of batch id's and associated properties.
    :status 500: Unknown error occurred during processing.

    **Response Syntax**:

    A list of Job objects.

    .. sourcecode:: json

       [
         {
           "job_id": "string",
           "job_tool": {
             "tool_id": "string",
             "tool_name": "string",
             "tool_description": "string"
           },
           "job_log_id": "string",
           "job_argument_list": [
             {
               "argument_key": "string",
               "argument_value": "string"
             }
           ]
         }
       ]

    :raises: May raise exceptions related to database operations or service availability.

.. http:get:: /batches/<batch_id>/jobs/<job_id>

    Returns attributes for the specific job

    :reqheader Authorization: API key or Bearer token for user authentication
    :status 200: Success. Returns a list of batch id's and associated properties.
    :status 500: Unknown error occurred during processing.

    **Response Syntax**:

    .. sourcecode:: json

       [
         {
           "job_id": "string",
           "log_id": "string",
           "hardware": {
             "filesystems": [
               "id"
             ],
             "memory": 123,
             "cpu": 123
           },
           "args": {
             "name": "value"
           },
           "status": "string",
           "reason": "string",
           "create_time": "string",
           "start_time": "string",
           "stop_time": "string",
         }
       ]

    :raises: May raise exceptions related to database operations or service availability.