REST API#

An EnSight session that is started using PyEnSight may enable the direct REST API. The REST API, which allows JavaScript code to directly access the EnSight Python APIs, is only available in EnSight 2024 R1 and later. To enable the REST API, you set the enable_rest_api keyword to True for the Launcher subclass ctor.

Note

The information here is for informational purposes only. The REST API has been defined, but it is not currently enabled in EnSight. It is scheduled for release in EnSight 2024 R1.

REST API enablement via PyEnSight#

You can start the REST API service via the PyEnSight local launcher:

>>> from ansys.pyensight.core import LocalLauncher
>>> s = LocalLauncher(enable_rest_api=True).start()
>>> s.load_data(f"{s.cei_home}/ensight{s.cei_suffix}/data/cube/cube.case")
>>> uri_base = f"http://{s.hostname}:{s.html_port}/ensight/v1/{s.secret_key}"

The base URI looks something like this, but the port and GUID can vary: http://127.0.0.1:36474/ensight/v1/b7c04700-0a27-11ee-be68-381428170733.

Basic REST API#

You can use the string from the previous example to execute REST calls via Python requests:

>>> import requests
>>> requests.put(uri_base+"/eval", json="ensight.objs.core.PARTS").json()
['@ENSOBJ=1022@']
>>> requests.put(uri_base+"/eval", json="ensight.objs.core.PARTS", params=dict(returns="DESCRIPTION,VISIBLE")).json()
[['Computational mesh', True]]

The REST calls use the REST API to run the ensight.objs.core.PARTS command and output something like ['@ENSOBJ=1022@'], a reference to object 1022. What the query option returns is then used to return the DESCRIPTION and VISIBLE attributes. In this case, the output for the second PUT is [['Computational mesh', True]].

Note

Examples here leverage Python requests to execute REST calls, but tools like cURL and Swagger can also be leveraged. The intended use of the REST API is via JavaScript to use fetch() from within a web page, making it possible to control and interact with a PyEnSight-launched EnSight instance directly from the browser. Moreover, both PyEnSight and REST calls can be used to talk to the same EnSight session, making it possible to communicate between browser JavaScript and PyEnSight Python scripts using the EnSight instance as a common communication hub.

Remote Python functions#

Continuing the example, the REST API can be used to define a Python function in the remote EnSight session. First define the function:

>>> foo_src = "def foo(n:int = 1):\n return list(numpy.random.rand(n))\n"
>>> requests.put(uri_base+"/def_func/myapp/foo", json=foo_src, params=dict(imports="numpy"))
<Response [200]>

The preceding code uses the provided function source code to define a function named foo in the myapp namespace. The function being defined should use keywords only, no positional arguments.

Note

If the namespace does not exist, it is created.

The function also makes use of the numpy module. A function must either import the module inside of the function or include the names of the modules in the imports query options as a comma-separated list of module names. Because numpy arrays do not directly support serialization to JSON, a list is used for the returned value.

Once the function has been defined, it can be called like this:

>>> requests.put(uri_base+"/call_func/myapp/foo", json=dict(n=3)).json()
[0.2024879142048186, 0.7627361155568255, 0.6102904199228575]

The returned JSON is a list of three random floating point numbers.

Direct commands#

The native API can be called directly using the REST API:

>>> requests.put(uri_base+"/cmd/ensight.view_transf.rotate", json=[5.2,10.4,0]).json()
0

The EnSight view rotates accordingly. The object API can also be called directly. You can get or set object attributes in various forms on single objects or lists of objects:

>>> requests.get(uri_base+"/ensobjs/ensight.objs.core/PARTS").json()
['@ENSOBJ=1022@']
>>> requests.get(uri_base+"/ensobjs/ensight.objs.core/PARTS", params=dict(returns="VISIBLE,__OBJID__")).json()
[[True, 1022]]
>>> requests.put(uri_base+"/ensobjs/1022/VISIBLE", json=False)
<Response [200]>
>>> requests.put(uri_base+"/ensobjs/setattrs", json=dict(objects=["1022"], values=dict(VISIBLE=False)))
<Response [200]>
>>> requests.put(uri_base+"/ensobjs/getattrs", json=[1022], params=dict(returns="DESCRIPTION,VISIBLE")).json()
{'1022': ['Computational mesh', False]}
>>> requests.put(uri_base+"/eval", json="ensight.objs.core").json()
'@ENSOBJ=220@'
>>> requests.put(uri_base+"/eval", json="ensight.objs.core", params=dict(returns="__OBJID__")).json()
220

You can specify objects by name (ensight.objs.core) or by number (220) and return any attributes of the objects in a single call, reducing the number of REST calls needed for complex operations.

Shared token security#

The REST API leverages shared secrets to control access to the EnSight instance. Every PyEnSight-launched instance has a shared secret token that must be provided in all REST calls. This shared secret token can be accessed using the PyEnSight secret_key attribute. All REST APIs expect that the token be specified in one of two ways:

  • The token can be passed as part of the URL path in this form: {LOCATION}/ensight/v1/{TOKEN}/{OPERATION}.

  • The token can be passed in an Authorization: Bearer TOKEN header. When you use this approach, you can pass any value in the URL path.

If you supply tokens using both methods, the token in the header is used.

REST API reference#

PUT /ensight/v1/{sessionid}/exec#

Exec Python command(s)

Run one or more strings as Python commands in the remote EnSight session.

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

Example request:

PUT /ensight/v1/{sessionid}/exec HTTP/1.1
Host: example.com
Content-Type: application/json

[
    "ensight.part.modify_begin()",
    "ensight.part.elt_representation('3D_feature_2D_full')",
    "ensight.part.modify_end()"
]
Status Codes:
PUT /ensight/v1/{sessionid}/eval#

Eval a Python command

Execute one string as a Python command in the remote EnSight session and return the result.

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

Query Parameters:

  • returns (string) – A comma separated list of attribute names to return when an ENSOBJ object is returned. ENSOBJ is the default which returns @ENSOBJ=123@.

Example request:

PUT /ensight/v1/{sessionid}/eval HTTP/1.1
Host: example.com
Content-Type: application/json

ensight.objs.core.unit_system()
Status Codes:

  • 200 OK –

    Successful operation

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

[
    "SI",
    "Metric SI",
    true,
    {
        "M": "kg",
        "L": "m",
        "T": "s",
        "K": "K",
        "Q": "A",
        "D": "rad",
        "I": "cd",
        "A": "mol"
    }
]

  • 400 Bad Request – Python error encountered during execution

  • 401 Unauthorized – Invalid sessionid

PUT /ensight/v1/{sessionid}/def_func/{app}/{funcname}#

Define a remote function

Create a function in the remote EnSight instance that can be called directly via the REST API.

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

  • app (string) – A namespace to place the new function in. Generally used to avoid name collisions and to provide a place to store session data. It must be a valid Python variable name.

  • funcname (string) – The name of the function to be defined

Query Parameters:

  • imports (string) – A list of modules that should be import before the function is defined.

Example request:

PUT /ensight/v1/{sessionid}/def_func/{app}/{funcname} HTTP/1.1
Host: example.com
Content-Type: application/json

"def funcname(app: SimpleNamespace, o: typing.Optional['ENSOBJ'] = None, s : str = 'VISIBLE') -> dict:
    v = o.getattr(s)
    return dict(s=v)"
Status Codes:
PUT /ensight/v1/{sessionid}/call_func/{app}/{funcname}#

Call a remote function

Call a previously defined remote function.

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

  • app (string) – A namespace to place the new function in. Generally used to avoid name collisions and to provide a place to store session data. It must be a valid Python variable name.

  • funcname (string) – The name of the function to be called.

Query Parameters:

  • returns (string) – A comma separated list of attribute names to return when an ENSOBJ object is returned. ENSOBJ is the default which returns @ENSOBJ=123@.

Example request:

PUT /ensight/v1/{sessionid}/call_func/{app}/{funcname} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "num_samples": 4,
    "source": "@ENSOBJ=120@"
}
Status Codes:
PUT /ensight/v1/{sessionid}/cmd/{nativecommandname}#

Run an EnSight native Python command

Execute the named EnSight native Python command with the parameters passed in the list of object in the request body.

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

  • nativecommandname (string) – The native python binding for a command language command.

Example request:

PUT /ensight/v1/{sessionid}/cmd/{nativecommandname} HTTP/1.1
Host: example.com
Content-Type: application/json

[
    33.7,
    -0.402,
    0.0
]
Status Codes:
GET /ensight/v1/{sessionid}/ensobjs/{objectid}/{attributeid}#

ENSOBJ attributes

Get an ENSOBJ attribute value

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

  • objectid (string) – The name of an EnSight object or an object id

  • attributeid (string) – An ENSOBJ attribute name like VISIBLE.

Query Parameters:

  • returns (string) – A comma separated list of attribute names to return when an ENSOBJ object is returned. ENSOBJ is the default which returns @ENSOBJ=123@.

Example request:

GET /ensight/v1/{sessionid}/ensobjs/{objectid}/{attributeid} HTTP/1.1
Host: example.com
Status Codes:
PUT /ensight/v1/{sessionid}/ensobjs/{objectid}/{attributeid}#

ENSOBJ attributes

Set an ENSOBJ attribute value

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

  • objectid (string) – The name of an EnSight object or an object id

  • attributeid (string) – The native python binding for a command language command.

Example request:

PUT /ensight/v1/{sessionid}/ensobjs/{objectid}/{attributeid} HTTP/1.1
Host: example.com
Content-Type: application/json

{}
Status Codes:
PUT /ensight/v1/{sessionid}/ensobjs/setattrs#

Multi-ENSOBJ setattrs

Set a collection of attributes on a collection of ENSOBJ objects.

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

Query Parameters:

  • suppress_errors (boolean) – If this is true and there is an error during the set operation, do not return an error/stop processing the entire list.

Example request:

PUT /ensight/v1/{sessionid}/ensobjs/setattrs HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "objects": [
        "ensight.objs.core",
        1234
    ],
    "values": {
        "VISIBLE": true,
        "DESCRIPTION": "example"
    }
}
Status Codes:
PUT /ensight/v1/{sessionid}/ensobjs/getattrs#

Multi-ENSOBJ getattrs

Get a collection of attributes on a collection of ENSOBJ objects.

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

Query Parameters:

  • returns (string) – A comma separated list of attribute names to return when an ENSOBJ object is returned. ENSOBJ is the default which returns @ENSOBJ=123@.

  • suppress_errors (boolean) – If this is true and there is an error during the set operation, do not return an error/stop processing the entire list. Also, no key will appear in the output object for objects which returned an error.

Example request:

PUT /ensight/v1/{sessionid}/ensobjs/getattrs HTTP/1.1
Host: example.com
Content-Type: application/json

[
    "ensight.objs.core",
    1234
]
Status Codes:

  • 200 OK –

    Successful operation. The object has keys for each value in the input array and the value will be an array of the output attribute values.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "ensight.objs.core": [
        false,
        "global object"
    ],
    "1234": [
        true,
        "wheels"
    ]
}

  • 400 Bad Request – Python error encountered during execution

  • 401 Unauthorized – Invalid sessionid

PUT /ensight/v1/{sessionid}/ensobjs/{objectid}/methods/{method}#

Run ENSOBJ method

Execute an ENSOBJ method and return the result.

Parameters:

  • sessionid (string) – The PyEnSight session secret key.

  • objectid (string) – The name of an EnSight object or an object id.

  • method (string) – The name of a method on the selected object.

Query Parameters:

  • returns (string) – A comma separated list of attribute names to return when an ENSOBJ object is returned. ENSOBJ is the default which returns @ENSOBJ=123@.

Example request:

PUT /ensight/v1/{sessionid}/ensobjs/{objectid}/methods/{method} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "args": [
        "param1",
        1.0
    ],
    "kwargs": {
        "num_samples": 4,
        "source": "@ENSOBJ=120@"
    }
}
Status Codes: