API Submissions

Users are able to create submissions by accessing the API for any assignments that they have access to. The Submitted Via filter in the Submissions tab shows whether the submission was created via API or in 1Data Gateway.

However, users require an API token to be generated first, see API Tokens.

This allows users to authenticate with the API via HTTP Bearer authentication.

     Note: The header of the HTTP request must contain:

Authorization: Bearer <API Token Here>

Example requests can be constructed using the Swagger docs, which can be accessed at {service address}/swagger-ui/index.html.

Submissions

When using the API to submit to 1Data Gateway, it is important that you follow the correct order for the calls:

  1. POST to the following endpoint to create a new, empty, submission:

    2. POST: /api/v1/assignments/{assignmentKey}/submission

    The {assignmentKey} is present in the URL when viewing an assignment in the 1Data Gateway UI, e.g. {EXAMPLE-ASSN-1} in the following URL:

    https://datagateway.{company}.com/my_assignments/EXAMPLE-ASSN-1/submissions

         Note: The {assignmentkey} will always contain ASSN.

    The JSON response will contain the {submissionreference}, which will be used in subsequent calls.

  2. Next, POST the contents of the input files to:

    POST: /api/v1/submissions/{submissionReference}/inputs

         Note: The body of the call must be form-data with a parameter name: file, type: file with the input file as the value.

    Here, you must pass the input path as a query parameter named dataStorePath.

    The path for each input can be found by selecting the Copy to Clipboard button in the specification configuration page.

    The specification configuration page with the copy to clipboard icon highlighted

  3. Once submission data has been uploaded, start the submission process by POSTing to:

    POST: /api/v1/submissions/{submissionReference}/start

  4. Wait for the submission process to complete. To see status of the submission, poll the status endpoint at:

    GET: /api/v1/submissions/{submissionReference}

    If the JSON returned has status equal to FINISHED the submission is completed.

  5. Use the JSON response from step four to obtain the {storedFilename} of any output files, and download them using the following endpoint:

    GET: /api/v1/submissions/{submissionReference}/outputs/{filename}

     Note: If an error occurs while processing the Submission, it will still end in the FINISHED state, but the errorMessage will be non-null. Check the Submission My Assignments and My Assignments tables for further information.