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.
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:
200 OK – Successful operation
400 Bad Request – Python error encountered during execution
401 Unauthorized – Invalid sessionid
- 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:
200 OK – Successful operation
400 Bad Request – Python error encountered during execution
401 Unauthorized – Invalid sessionid
- 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:
200 OK – Successful operation
400 Bad Request – Python error encountered during execution
401 Unauthorized – Invalid sessionid, app or funcname
- 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:
200 OK – Successful operation
400 Bad Request – Python error encountered during execution
401 Unauthorized – Invalid sessionid
- 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:
200 OK – Successful operation
400 Bad Request – Python error encountered during execution
401 Unauthorized – Invalid sessionid
- 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:
200 OK – Successful operation
400 Bad Request – Python error encountered during execution
401 Unauthorized – Invalid sessionid
- 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:
200 OK – Successful operation
400 Bad Request – Python error encountered during execution
401 Unauthorized – Invalid sessionid
- 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:
200 OK – Successful operation
400 Bad Request – Python error encountered during execution
401 Unauthorized – Invalid sessionid