API
  • API Index
  • Batch API
  • Content Negotiation
  • Dynamic Paths
  • Hierarchy API
  • List API
  • Quick Reference
  • Time Series API
  • Views
      • Configuration
  • Overview
  • Application Configuration
  • Documentation Configuration
  • Spec Configuration
      • Features
  • API Testing
  • Asynchronous Processing
  • Cassandra Time-Series Engine
  • Cassandra Integration
  • Default Controller Customisation
  • Documentation
  • Geospatial Filtering
  • Model Documentation
  • PostgreSQL Integration
  • Excel Spreadsheet Format
      • Tutorials
  • Step-by-Step Guide
  • Archetype Setup
  • Logging
  • Prometheus
  • Sentry Logging
      • UI Customisation
  • UI Customisation
  • SASS Build Chain
  • Shared Layout
  • API Documentation
  • Model Documentation
  • Results
    • sapi-nt v current

    Batch API

    Some endpoints support asynchronous processing for large requests.

    You can send a request to a enabled endpoint in “batch mode” by appending /batch to the end of the URL path. Path and query parameters can be used in the same way as usual for that endpoint. For example, the path:

    /stream/AB-01/package?_view=compact&min-mass=1000

    could be rewritten as

    /stream/AB-01/package/batch?_view=compact&min-mass=1000

    in order to perform the same request asynchronously.

    If the results of the request have already been cached, they will be downloaded immediately. Otherwise, you will be redirected to the batch status page, which will show some information about the state of the request in the queue.

    You can refresh the status page to check the progress of an ongoing request. Once processing is complete, it will show the download URL for the results. Alternatively, you can access the results by resending the original batch request.

    Some requests may fail due to invalid parameters, or by exceeding resource limitations. In this case, the batch status page will indicate that the request has failed, and the reason for the failure will be logged by the application.

    Failed requests can be attempted again by sending another request to the batch endpoint.

    Note

    The batch API does not currently display the reason for failed requests to users.

    Batch Status

    You can append /status to the end of the batch URL path to get information about the state of the batch request in the queue. So the URL above could be written as:

    /stream/AB-01/package/batch/status?_view=compact&min-mass=1000

    The response will be in JSON format, having the following properties:

    Property Meaning
    key The uniquely identifying key for the request. This will usually be some composition of the request path and query parameters
    status The status of the request. Possible values are Pending, InProgress, Completed and Failed.
    url The URL from which the results of the request can be downloaded, if it is complete.
    positionInQueue The position of the request in the queue. A value of 0 denotes that the request is already in progress.
    eta The estimated time until the request will be complete. This may not be representative of the actual time to completion.
    started The Unix timestamp of the time when the request started executing, if it has been started.

    POST Method

    You can send HTTP POST requests to initiate and inspect the status of batch requests. Unlike GET requests, they will not return the result data for the request.

    You can send a POST request to any batch endpoint to add the request to the queue if it hasn’t been added already. If the request was added successfully, or was already added, the response will redirect you to the status page for your request. You will be redirected even if the request has already been completed.

    Content Negotiation

    The batch API supports content negotiation using the _format query parameter only. Batch endpoints support the same content types as their non-batch counterparts.