Creating an Oasys API Client Application
Introduction
This document explains how to create applications that call Oasys APIs.
Licence
The API requires a licence to run. For Arup staff this should be automatically acquired. Other users are required to have the desktop product installed prior to running the API and will be prompted to enter valid API licence key and password upon first use. Please contact us at oasys@arup.com if you would like to purchase a licence or experience any licencing issues.
System Requirements
You must run your API application on Windows 10, 64-bit. You must install either .NET Core 3.1 or .NET 5 or later even if you're going to write your application in Python. If you're using Python you'll also need the .NET Core 3.1 Runtime.
See Installing Prerequisites Without Admin Rights if you need to install any prerequisites with Administrator rights on a Windows PC.
Supported Languages
.NET
You can call the API with any of the .NET languages (C#, F# or Visual Basic).
See Getting Started With C# and .NET for more information.
Python
We support Python 3.7 or later. (Note that this must be CPython, not IronPython.)
See Getting Started With Python for more information.
Samples
The oasys-api-samples repository contains working examples in both C# and Python. The samples make a great starting point for your project.
Notes
OasysUnits
The API relies on strongly typed value for lengths, masses and other units. This behaviour is provided by the OasysUnits.
We decided to do this because:
- It makes it much harder to "cross wire" values by mistake
- It makes it easy to use different scales such as inches, millimetres and meters for lengths
Consider this example. The call to ILoad.Create() creates a load for
a section in AdSec. Without OasysUnits it's not very clear what scales to use
for the arguments:
var load = ILoad.Create(-100000, 60000, 0); // N.B. This doesn't compile. It's just for illustration.
With OasysUnits, it's obvious what units are being used ...
load = ILoad.Create(Force.FromKilonewtons(-100), Moment.FromKilonewtonMeters(60), Moment.Zero);
... and the caller can use different units if they prefer.
load = ILoad.Create(Force.Newtons(-100000), Moment.FromNewtonMeters(60000), Moment.Zero);
OasysUnits does not support infinite values. Where the API needs to return a value that is infinite, then it will return a very large number instead. This will be 1e+100 unless the value has been scaled.
Thread Safety
API objects are not thread safe unless stated otherwise in the API documentation. The API will throw an exception if you create an object on one thread and then try to access it from another thread.
You can use multiple threads in your application as long as those threads keep their API objects to themselves.
License operations (activate/deactivate and acquire/release network seats) cannot be undertaken concurrently.