API Docs
1Data Gateway uses RESTful APIs which are publicly accessible and secured using tokens.
Administrators can find a link to the Swagger docs via the in 1Data Gateway .
All users are able to access the APIs but Submission management and assignments are limited to the submission owner/creator.
All users can create submissions if it is part of their assignment and they have an API key.
All authenticated API endpoints require the client to provide an API token via HTTP Bearer authentication.
Note : Unless noted, the API request and response bodies are in JSON format.
API Tokens are required on a per User basis and are necessary for authentication of the API endpoints.
The API token must first be created individually for each User from the Users .
Note : The token becomes invalid if it passes the expiry date or the User's account becomes disabled.
Note : For security purposes we recommend that tokens are carefully managed and only supplied to trusted individuals.
From the API Tokens tab of a Users page click the icon to create a new API token.
Fill in the name, description, and expiry date, and then click the icon.
Copy the API token with the and click when you've stored the token somewhere safe.
From the API Tokens tab:
Click the button to edit and update the API settings.
Click the button, then confirm with the button to remove an API token.
The 1Data Gateway API can be leveraged to perform analytics in external applications.
The following API calls can be used for Specification reports on:
Rule conformance over time.
/api/v1/reports/specification/{specificationKey}/rule_conformance
Submissions over time.
/api/v1/reports/specification/{specificationKey}/submissions
Task performance over time.
/api/v1/reports/specification/{specificationKey}/task_conformance
Replace the {specificationKey}
with the Specification Key found in the Specifications .
When using the API to submit to 1Data Gateway , it is important that you follow the correct order for the calls:
POST to the following endpoint to create a new, empty, submission:
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.
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
Once submission data has been uploaded, start the submission process by POSTing to:
POST: /api/v1/submissions/{submissionReference}/start
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.
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.