Skip to main content

REST API

ArupCompute automatically generates a REST API for each library hosted. You can use it to list the calculations and execute them.

For a full description of the ArupCompute API see the swagger documentation here.

Authentication​

Calls to ArupCompute need to be authenticated against the Arup Azure AD Authentication and provide an OAuth 2.0 Bearer Token.

If you are using .NET you can use the arupcompute-connect-dotnet library.

If you are using Python have a look at arupcomputepy.

For other languages check out the Azure AD Authentication Libraries.

Authentication flows​

See the Microsoft documentation for a thorough explanation of all of the flows, however some commonly used ones are listed below:

Integrated Windows authentication flow​

This flow is used by desktop applications (for instance the ArupCompute Grasshopper component) which uses the account information on your Windows device to verify your identity. This is the most user friendly flow as the user is unlikely to be aware that it is even happening. Because of the tight integration with Windows systems this flow is currently only available from .NET languages.

Interactive or implicit grant flows​

This flow prompts the user for a username and password to verify that they have access to ArupCompute. Most typically encountered in web applications (e.g. ArupCompute web interface).

Device code flow​

This is used where the application has limited access to user accounts and cannot send password information securely. In this flow the user is given a code to enter into a website for verification purposes. This is the default authentication flow in arupcomputepy.

Client secret flow​

This flow uses a pre-registered secret value to authenticate against ArupCompute. Because this flow allows any person with the client secret to access ArupCompute it is the most risky of all of the mentioned flows. To safeguard against unintended access this secret must be stored securely. For this reason this flow is not available from web browsers.

Registering an application for API access​

To register an application (website, service etc.) for ArupCompute API access you will need access to the Arup Azure account. This can be arranged with IT.

Firstly, head to the Arup Azure portal

Create a new 'App Registration'

App Registration

Choose 'public client' and use a redirect uri of the form 'myapp://auth'

Important info to keep a note of from the overview page is:

  • Application (client) ID
  • Directory (tenant) ID

Overview page

Next go to 'API permissions' > 'Add a permission', then request 'ArupComputeAPI'.

API permissions

Request API permission

If your application will be using an 'on-behalf-of' flow (e.g. a website) select 'delegated permissions' and you are done.

If your application is using a client secret flow (e.g. python process running on a server) you will need to select 'application permissions'. Application permissions require Arup IT approval - raise a service now request with the cloud computing team.

Delegated application

Registering a client secret​

Go to the 'Certificates & secrets' page and create a 'new client secret'.

Client secret

Give the secret a descriptive name, set an expiry date, and copy it somewhere secure.

Secret

When access has been approved by Arup IT you will now be able to set up your application to use the ArupCompute API via a client secret flow. This flow is supported by both arupcompute-connect-dotnet and arupcomputepy.

Resources​

Generally, see the swagger docs for documentation of the resources and enpoints available on the ArupCompute API. Refer to this section for details which are not made obvious by the swagger docs. This section will not repeat information which can be understood from the swagger docs.