REST API

AWF provides a REST API so that you can intgrate AWF as part of your automation solution. Through this API, you can submit jobs to any workflow with a simple HTTP request. This section will provide simple examples that show how to GET information about workflows, and POST jobs to a particular workflow.
For more detailed information on the API endpoints, check out the Swagger API documentation (opens new window).

🔑 Get Authorization Token

For security all API requests need to authenticate with the AWF API backend. In order to do this you will need to authenticate with Azure AD (opens new window). First you will need to register your app (opens new window) and get the TENANT_ID to authenticate against the correct endpoint.

POST    https://login.microsoftonline.com/organizations/{TENANT_ID}

parameters
client_id - The client id obtained from registering the app on Azure App registrations.
returns
auth_token - You will need this to add to the header of every subsequent request.

📖 Get information about a workflow

In order to retrieve a list of all available workflows simply run:

GET     https://awf.arup.com/api/workflow/

parameters
auth_token - Add the acquired Bearer token with the format Bearer azuread-oauth2 {AUTH_TOKEN}.
returns
workflow_url - this url can be used to access more detail about the workflow.

⚡ Submitting a workflow run

The API can be used to start workflow runs.

Initialize a workflow run

Create a new workflow run to attach information about a workflow prior to running it.

POST     https://awf.arup.com/api/run/

headers
auth_token - The acquired Bearer token with the format Bearer azuread-oauth2 {AUTH_TOKEN}. parameters
workflow_url - The URL of the workflow that needs to be run. status - This is the run status of the workflow. Set to -2 to initialize a new workflow run.
returns
run_id - This id can be used to make subsequent API calls to add information to the workflow run.

Upload a file

Usually a workflow will require an input file to run the workflow on. This is done by first requesting a signed URL to upload the file to.

POST     https://awf.arup.com/api/resource/

headers
auth_token - Add the acquired Bearer token with the format Bearer azuread-oauth2 {AUTH_TOKEN}.
parameters
name - The name of the file.
description - A desciption of what the file is.
filename - The name of the file.
type - The file type. Set to 0 to indicate it is an input file.
mime_type - The file MIME type.
run - The run_id which the file pertains to.
returns
signed_url - This id can be used to make subsequent API calls to add information to the workflow run.
The signed url can be used to actually upload the file, it will look something like this:

PUT     https://s3.amazonaws.com/{{S3_BUCKET}}/{{path}}?AWSAccessKeyId={{S3_ACCESS_KEY_ID}}&Expires={{expire_date}}&Signature={{signature}}

headers
Content-Type - The file MIME type to identify the type of file that is being uploaded.
parameters
file - The file to upload.

Run the workflow

Submit a job to the queue, passing in the workflow run_id as an argument, as well as additional information about the workflow run.

PATCH     https://awf.arup.com/api/run/

headers
auth_token - Add the acquired Bearer token with the format Bearer azuread-oauth2 {AUTH_TOKEN}. parameters
workflow - The run_id of the workflow run.
status - The status code of the workflow run. Use -1 to submit the workflow to the queue.
arguments - A list of workflow arguments.

⏲ Checking the workflow status

Check the status of a running workflow to see if it is still running or it has completed. Use the run_id to retrieve the information about your run. Completed runs have a status code of 1 if successful and status codes of 2 and higher an error occured during the workflow.

GET     https://awf.arup.com/api/run/{RUN_ID}/

headers
auth_token - Add the acquired Bearer token with the format Bearer azuread-oauth2 {AUTH_TOKEN}.

📁 Download workflow results

After the workflow run completes, you can get a list of results files (resources) that are available to download using the run_id:

GET     https://awf.arup.com/api/privatedata/resource/

headers
auth_token - Add the acquired Bearer token with the format Bearer azuread-oauth2 {AUTH_TOKEN}. parameters
run_id - The run_id of the workflow run.
returns
Each resource will have a url attribute that contains the download link to the resource.

You can download the resource using that url attribute, which will look something like:

GET     https://awf.arup.com/api/privatedata/resource/{RESOURCE_ID}/

headers
auth_token - Add the acquired Bearer token with the format Bearer azuread-oauth2 {AUTH_TOKEN}.