APPENDIX F - HTTP REST API F.1 OVERVIEW
PLAXIS provides an HTTP based API. This API allows a developer or user to do normal PLAXIS tasks such as creating projects, firing regular commands as found on the existing command line, performing meshing and calculations. In addition, unique representations of Plaxis objects can be retrieved, kept, and then used in later operations, such as the fetching of their properties and methods, as well as calling methods. This provides additional flexibility and power to the existing command line.
There are several categories of actions that can be performed via the HTTP API. Each of these have their own URL path, as follows:
/environment Start, close, recover or open projects
/commands Fire regular PLAXIS command line commands and fetch any created objects
/members Fetch the members of objects /propertyvalues Fetch the property values of objects
/namedobjects Fetch existing objects by their command line names /list Fetch items from listable objects
/enumeration Fetch all possible values of enumeration objects
/exceptions Get information about exceptions that occurred outside the server requests
/tokenizer Offers tokenization services All request data must be encoded using UTF-8.
F.2 OBJECT REPRESENTATIONS
Resources which create or retrieve objects return representations of those objects. These representations comprise a Globally Unique Identifier (GUID), a type name, and a flag indicating whether the object is listable or not. The JSON structure for this representation is as follows:
"guid": <string>
"islistable": <boolean>
"ownerguid": <string>
"type": <string>
The server can recognise and retrieve information about objects contained within the
PLAXIS project based on that object's GUID. This means that, for example, a particular
PLAXIS object can be created using the /commands resource, and then later the values
of that object's properties can be retrieved by sending that object's GUID in a request to
the /propertyvalues resource. The same GUID can be used in the creation of additional
objects by sending it in a request to the /commands resource. If the object is listable,
sending the guid as part of a request to the /list resource will enable access to the
object's properties by index, and so on. The ownerguid is only returned for objects that
are intrinsic properties. It is the guid of the owning object.
F.3 USING A WEB BROWSER TO ACCESS THE API
It is possible to perform a subset of the actions that are described below by using a browser address bar. This can be useful for quickly viewing the data representations that are returned from the API.
There is a limitation to the complexity of queries that can be made in this mode, which means that certain resources and actions are not possible. This includes the /list resource, and also the querying of specific named properties in the /propertyvalues resource (however it is still possible to query all properties for an object using a browser address bar).
Each resource description below includes an example action using the address bar.
F.4 HTTP API RESOURCES F.4.1 /environment
This resource is for managing projects. Creating, restoring, closing or opening a project are permitted. If a project is opened, then a filename string is supplied for locating an existing project locally, or otherwise becomes the name of a new project.
Note that it is not possible to save projects via this resource. Instead, fire a save command using the /commands resource.
Method: POST Data parameters
{"action":
{"name": *1 <string> from {"new", "open", "close", "restore"}*,
"filename": *1 <string>*
}}
Data parameters example
{"action":
{"name": "open",
"filename": "my_plaxis_project.p2dx"
}}
{"action":
{"name": "close",
"filename": ""
}}
Success responses
Code Reason
200 OK
Error responses
Code Reason
404 STATUS NOT FOUND "Incorrect or unspecified action: [action-name]"
404 STATUS NOT FOUND "Incorrect or unspecified file name, or not a valid project: [filename]"
400 BAD REQUEST "Syntax of request could not be understood by the server."
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
Example JSON request
payload = {"action": {"name": "new", "filename": ""}}
headers = {"content-type": "application/json"}
response = requests.post("/environment", data=json.dumps(payload), headers=headers)
Example browser request
http://localhost:8001/environment?action.name=new
http://localhost:8001/environment?action.name=open&action.filename=my_plaxis_project.p2dx
F.4.2 /commands
This resource allows all standard commands (see command reference pages) to be run on an active PLAXIS project. Any objects created as the result of commands are represented in the response.
The server can recognise and "translate" GUIDs that refer to existing objects, as part of the command string. This means that it is possible to use GUIDs in the place of regular command line names to refer to other objects. This is beneficial, because the names of objects may be changed over the lifetime of a project (e.g. using the rename command), but the GUID remains fixed.
For example, it is possible to create a line between two existing points by referring to the GUIDs of those points in the command string of a request:
line <guid1> <guid2>
Note that a command that fails on the command line will not result in an error response from the server. These are treated as successful requests to the API. The server response indicates whether a command failed or not in the 'success' field. (See example below.) Whether the command succeeded or not, the 'additionalinfo' field indicates the response from that action as seen on the regular command line.
Method: POST Data parameters
{"action":
{ "commands":
[*{1, ...}[<string>]*
} ] }
Data parameters example
{"action":
{"commands":
["point 1 2"
}] }
{"action":
{"commands":
["embeddedbeamrow 4 4 {860C1FC5-BDE1-4887-98A2-8FE20B61FCD5}"
}] }
{"action":
{"commands":
["bad"
}] }
Success responses
Code Reason
200 OK
Data
{"commands":
[{
"feedback":
{"extrainfo": "Added Point_1",
"returnedobjects":
[{
"islistable": true,
"type": "Point",
"guid": "{860C1FC5-BDE1-4887-98A2-8FE20B61FCD5}"
],}
"debuginfo": "",
"success": true,
"errorpos": -1
"command": "point 1 2"}, ]}
}
{"commands": [ {"feedback": {
"extrainfo": "Added Point_3\r\nAdded Line_1\r\nAdded EmbeddedBeamRow_1",
"returnedobjects": [ {"islistable": true,
"type": "Point",
"guid": "{92851C68-561A-4C21-9ACD-46F50905FD4E}"
},{"islistable": true,
"type": "Line",
"guid": "{7DB7DF8E-1FE4-4624-A3D2-F682DB9C8F18}"
},{"islistable": false,
"type": "EmbeddedBeamRow",
"guid": "{A678F396-C8F3-41EE-9A8E-5798BB0B6054}"
"debuginfo": "",}],
"success": true,
"errorpos": -1
},"command": "embeddedbeamrow 4 4 Point_1"
}}]
Code Reason
200 OK
Data
{"commands":
[ {
"feedback":
{"extrainfo": "Command \"bad\" is not recognized as a global command.
Check the spelling or try specifying a target object.",
"debuginfo": "",
"success": false,
"errorpos": 1 },"command": "bad"
] } }
It is also possible for some commands to respond with an arbitrary JSON object. In these cases the 'type' field of the 'returnedobjects'will be set to 'JSON'.
{ "commands": [
{ "command": "export ObservablePlot_1 800 600",
"feedback": {
"returnedvalues": [],
"success": true,
"returnedobjects": [ { "islistable": false,
"guid": "{00000000-0000-0000-0000-000000000000}",
"type": "JSON",
"json": {
"data": "...",
"ContentType": "image/png"
}],}
"extrainfo": "OK",
"errorpos": -1,
"debuginfo": ""
}] } }
Here the command returned an associative dictionary containing the 'ContentType'field.
This will indicate what the rest of the dictionary will contain. In this particular case where
the 'ContentType'is 'image/png'the dictionary will contain an additional 'data'field whose
value is a base64 encoded PNG image.
The 'json'field does not necessarily have to be a dictionary, it can also be an integer or any other type allowed in JSON.
Error responses
Code Reason
400 BAD REQUEST "Syntax of request could not be understood by the server."
404 STATUS NOT FOUND "Commands not specified"
405 METHOD NOT ALLOWED "No active project"
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
Example JSON request
payload = {"action": {"commands": ["point 1 2"]}
headers = {"content-type": "application/json"}
response = requests.post("/commands", data=json.dumps(payload), headers=headers)
Example browser request
http://localhost:8001/commands?action.commands=gotostages
F.4.3 /members
This resource fetches the members (properties and methods) of an existing object within PLAXIS, identified by its GUID.
Property members are represented as objects.The type names of these objects are simplified in comparison to their type names within PLAXIS. This means that all 'Text' subtypes for instance will be simply described as having a type of 'Text'. The same principle applies to numerical, boolean, enumeration and object types.
Method members are represented as names only.
Method: POST Data parameters
{"action":
{"members":
[*{1,...}[GUID string]*
}] }
Data parameters example
{"action":
{"members":
["{68A2C1A7-924B-46C3-89DF-F597DAADC359}"
}] }
{"action":
{ "members":
["bad"
} ] }
Success responses
Code Reason
200 OK
Data
{"queries": {
"{68A2C1A7-924B-46C3-89DF-F597DAADC359}": {
"extrainfo": "",
"success": true,
"properties": {
"z": {
"islistable": false,
"ownerguid": "{68A2C1A7-924B-46C3-89DF-F597DAADC359}",
"type": "Number",
"guid": "{5FCCF1CC-7576-4565-B931-DE54241EA21B}"
},"y": {
"islistable": false,
"ownerguid": "{68A2C1A7-924B-46C3-89DF-F597DAADC359}",
"type": "Number",
"guid": "{D52CBED3-8C59-4967-A5BA-89ECE6E9BD94}"
},"x": {
"islistable": false,
"ownerguid": "{68A2C1A7-924B-46C3-89DF-F597DAADC359}",
"type": "Number",
"guid": "{25DA6A75-4F25-42F3-9654-3672A93FCE1F}"
},"Name": {
"islistable": false,
"ownerguid": "{68A2C1A7-924B-46C3-89DF-F597DAADC359}",
"type": "Text",
"guid": "{A4209590-9487-4B98-9966-34A6A58DBE2D}"
},"Comments": {
"islistable": false,
"ownerguid": "{68A2C1A7-924B-46C3-89DF-F597DAADC359}",
"type": "Text",
"guid": "{9430592C-7D5D-4735-B572-2B29C87FBF1F}"
},}
"commands": [
"echo","__dump","commands","rename","set","info","__observers","setproperties","move","rotate","rotateline"],
"commandlinename": "Point_1"
}} }
{"queries": {
"{0D04D0CB-86BF-4430-882C-FA56E45DF7AB}": {
"extrainfo": "GUID does not refer to object in registry: {0D04D0CB-86BF-4430-882C-FA56E45DF7AB}",
"success": false }}
} {
"queries": {
"bad": {
"extrainfo": "Supplied string is not a valid GUID: bad",
"success": false }}
}
Error responses
Code Reason
400 BAD REQUEST "Syntax of request could not be understood by the server."
404 STATUS NOT FOUND "No GUIDs specified"
405 METHOD NOT ALLOWED "No active project"
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
Example JSON request
payload = {"action": {"members": ["{9C5875EE-ABA4-4DC2-9E81-1FF839215232}"]}}
headers = {"content-type": "application/json"}
response = requests.post("/members", data=json.dumps(payload), headers=headers)
Example browser request
http://localhost:8001/members?action.members={0D04D0CB-86BF-4430-882C-FA56E45DF7AB}
F.4.4 /propertyvalues
This resource provides the current values of particular properties of PLAXIS objects. If a property is itself an object (such as the point properties of a line), then it is represented as a full object. If a property is a primitive value type, then the relevant primitive value is returned.
There are two ways of calling this resource. One is to supply just a guid of the owner object, in which case all properties of this object are represented in the response. The other way is to supply not just the owner guid, but also a property name and an optional phase parameter. Such a structure is treated as a request for one single property. If that property is staged, and the supplied phase guid is valid, then the value for that property and phase is returned.
Method: POST Data parameters
{"action":
{"propertyvalues":
[*{1} GUID string*]
} }
{"action":
{"propertyvalues":
{"owner": *{1} GUID string*
("phaseguid: *{1} GUID string*) }
} }
Data parameters example
{"action":
{"propertyvalues":
["{D4981EA8-EC07-471D-A8C3-7510B4F74F25}"]
}}
{"action":
{"propertyvalues":
{"owner": "{D4981EA8-EC07-471D-A8C3-7510B4F74F25}"
"propertyname": "Active"
"phaseguid": "{C3581EA8-FB07-5344-A8C3-569359320603}"
}}
Success responses
{"queries": {
"{D4981EA8-EC07-471D-A8C3-7510B4F74F25}": {
"extrainfo": "",
"success": true,
"properties": {
"Second": {
"islistable": true,
"type": "Point",
"guid": "{A67959C9-C12D-41D6-8136-52C1E5711165}"
},"Length": 6.92820323027551,
"First": {
"islistable": true,
"type": "Point",
"guid": "{4B889C3F-7F5C-4611-8D31-F4A39C71B11A}"
},"Name": "Line_1",
"Comments": ""
}} }}
{"queries":
{"{A10835D7-AE38-449C-BF67-6C9CE22705BD}":
{"extrainfo": "",
"properties": {"Comments": ""},
"success": true } }
}
Error responses
Code Reason
400 BAD REQUEST "Syntax of request could not be understood by the server."
404 STATUS NOT FOUND "No GUIDs specified"
405 METHOD NOT ALLOWED "No active project"
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
Sample JSON request
payload = {"action": {"propertyvalues": ["{9C5875EE-ABA4-4DC2-9E81-1FF839215232}"]}}
headers = {"content-type": "application/json"}
response = requests.post("/propertyvalues", data=json.dumps(payload), headers=headers)
Sample browser request
http://localhost:8001/propertyvalues?action.propertyvalues={0D04D0CB-86BF-4430-882C-FA56E45DF7AB}
F.4.5 /namedobjects
Supplies a representation of objects within PLAXIS which are identified by their
command line name. This is useful when accessing internal lists of objects within Plaxis with known names, such as lists of particular user features or geometric objects. This resource can also be used to retrieve unique representations of objects for which the command line name is known, such as 'Point_1'.
Method: POST Data parameters Example Request:
{"action":
{"namedobjects":
[ "namedobjects": ["Points"]
}] }
{"action":
{"namedobjects":
[ "namedobjects": ["Plate_1"]
}] }
Success responses
Code Reason
200 OK
Data
{
"namedobjects": {
"Points": {
"extrainfo": "",
"success": true,
"returnedobject": {
"islistable": true,
"type": "ModelGroup",
"guid": "{32871FF1-809C-470A-94B0-4B56B28BC67B}"
}} }}
Code Reason
200 OK
Data
{"namedobjects": {
"Plate_1": {
"extrainfo": "",
"success": true,
"returnedobject": {
"islistable": false,
"type": "Plate",
"guid": "{C0C4EDA6-DFF7-4593-A280-A1EC20D5EADD}"
}} }}
Error responses
Code Reason
400 BAD REQUEST "Syntax of request could not be understood by the server."
404 STATUS NOT FOUND "No object names specified"
405 METHOD NOT ALLOWED "No active project"
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
Sample browser request
http://localhost:8001/namedobjects?action.namedobjects=Lines http://localhost:8001/namedobjects?action.namedobjects=Phases
F.4.6 /list
Provides the ability to perform read operations on lists within PLAXIS, such as getting values at particular indices, finding the number of objects in the list, and filtering.
Method: POST Data parameters Example request:
{"action": {"listqueries": [{"guid": "{CF1DECEB-A28D-4609-B38C-8D3FF5E573A1}",
"method": "sublist",
"startindex": 0,
"stopindex": 1]}}
{"action": {"listqueries": [{"guid": "{CF1DECEB-A28D-4609-B38C-8D3FF5E573A1}",
"method": "count"]}}
{"action": {"listqueries": [{"guid": "{CF1DECEB-A28D-4609-B38C-8D3FF5E573A1}",
"method": "index",
"startindex": 0]}}
Success responses
{"listqueries": [{"extrainfo": "",
"guid": "{CF1DECEB-A28D-4609-B38C-8D3FF5E573A1}",
"methodname": "sublist",
"outputdata": [{"guid": "{81A754C8-1393-48BA-AD6E-5F6953F9FBE7}",
"islistable": true,
"type": "Point"}],
"startindex": 0,
"stopindex": 1,
"success": true}]}
{"listqueries": [{"extrainfo": "",
"guid": "{CF1DECEB-A28D-4609-B38C-8D3FF5E573A1}",
"methodname": "count",
"outputdata": 5,
"success": true}]}
{"listqueries": [{"extrainfo": "",
"guid": "{CF1DECEB-A28D-4609-B38C-8D3FF5E573A1}",
"methodname": "index",
"outputdata": [{"guid": "{81B754C8-1353-48BA-AD6E-5A6953F9CBE5}",
"islistable": true,
"type": "Point"}],
"success": true}]}
Error responses
Code Reason
400 BAD REQUEST "Syntax of request could not be understood by the server."
405 METHOD NOT ALLOWED "No active project"
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
Sample browser request
Not currently possible to call this resource via the browser address bar.
F.4.7 /enumeration
Provides a list of all possible enumeration values of one or more enumeration objects, when supplied with their GUIDs.
Success responses
Code Reason
200 OK
Data
{"queries": {
"{31AFFD41-0EB4-4A67-94F4-298642E17507}": {
"extrainfo": "",
"success": true,
"enumvalues": {
"hinged": 1,
"free": 2,
"rigid": 0 }}
}}
Code Reason
200 OK
Data
{"queries": {
"{0B4774CE-3307-4B86-B644-BFDE82CF3AAA}": {
"extrainfo": "GUID does not refer to object in registry:
{0B4774CE-3307-4B86-B644-BFDE82CF3AAA}",
"success": false }}
}
Code Reason
200 OK
Data
{"queries": {
"{C896C54E-1CBA-4B0F-9987-E1FF57A9131E}": {
"extrainfo": "Guid {C896C54E-1CBA-4B0F-9987-E1FF57A9131E} does not refer to an enumeration intrinsic property type.",
"success": false }}
}
Error responses
Code Reason
400 BAD REQUEST "Syntax of request could not be understood by the server."
405 METHOD NOT ALLOWED "No active project"
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
F.4.8 /exceptions
Exceptions that occur during execution of a server request are automatically caught and returned as error result in the response of that request. Exceptions however may also happen independently of the requests, e.g. because a problem during repainting. In such situations, an exception message box may be displayed by the application. This resource allows access to information about this type of exceptions.
The getlast variant will clear the last exception message on the server, while the peeklast variant will leave it in place.
Method: POST
Data parameters
{"action":
{"name": *1 <string> from {"getlast", "peeklast"}*
}}
Data parameters example:
{"action":
{"name": "getlast"
}}
{"action":
{"name": "peeklast"
}}
Success responses
Code Reason
200 OK
Data
{"exceptions": [
"date/time : 2015-04-17, 16:09:46, 750ms\r\ncomputer name : PC075\r\nwts client name : ...etc..."
}]
Error responses
Code Reason
400 BAD REQUEST "Syntax of request could not be understood by the server."
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
Example JSON request
payload = "action": "name": "getlast"
headers = "content-type": "application/json"
response = requests.post("/exceptions", data=json.dumps(payload)
headers = headers)
Example browser request
http://localhost:8001/exceptions?action.name=getlast
F.4.9 /tokenizer
Allows parsing a command line string into the separate tokens according to the PLAXIS
command line language. A token is a sequence of one or more characters that together
form a basic indivisible entity of source code.
Each token has the following properties:
• type: indicates what type of token it is (see list below)
• value: which is the parsed representation of the item (e.g. the token consisting of the characters 10 will resolve to be of integer type with value 10).
• position: indicates the start position of the token in the original string (0-based)
• length: the number of characters the token consumed from the original string The following types of tokens exist:
• identifier: something that will act either as command or as object identifier
• comment: a piece of comment, i.e. a sequence of characters starting with # up to the end of the string. The value of the token includes the starting # sign. It has one additional parameter for getting the text after the # sign:
• content: e.g. running in the case of #running
• externalinterpreter: a line that should be executed by an external interpreter, e.g.
/output echo Points. The value of the token includes the starting / sign. It has three additional properties:
• interpretername: e.g. output in the case of /output echo Points
• externalcommand: e.g. echo Points in the same case
• content: e.g. output echo Points in the case of /output echo Points
• text: identifies a string, which may be enclosed between 1 or 3 sets of single or double quotes ( ',''',","""). The value of a text token includes the surrounding quotes. It has one additional parameter for getting the text inside the quotation marks:
• content: e.g. input in the case of "input" or """input"""
• operand tokens:
• bracket: identifies a bracket type. Bracket tokens have additional properties:
• brackettype: can be round, square, curly for (),[],{} respectively
• bracketstate: can be open or close for ([{ respectively )]} .
• member: used to separate an object from its members (e.g. the . in Line\_1.Beam)
• comma, plus, minus, multiplier, divider, assign: currently unused, but they are the , , +,-,*,/,= operands respectively
• numerical tokens:
• integer: represents a number that can be represented by a 32-bit signed integer
• float: represents a number that can be represented as a floating point value
Method: POST
Data parameters
{"action":
{"tokenize":
[*{1,...}[string]*
}] }
Data parameters example
{"action":
{"tokenize":
["point 10"
}] }
{"action":
{"tokenize":
["point 10", "point 8"
}] }
{"action":
{"tokenize":
["a ?"
}] }
Success responses
Code Reason
200 OK
{"tokenize":
[{
"tokens": [ {"position": 0,
"length": 5,
"type": "identifier",
"value": "point"}, {"position": 6,
"length": 2,
"type": "integer",
"value": 10},
"success": true,],
"extrainfo": "",
"errorpos": -1
"tokenize": "point 10"}, ]}
}
Data
{"tokenize":
[ {
"tokens": [ {"position": 0,
"length": 1,
"type": "identifier",
"value": "a"},
"success": false,],
"extrainfo": "Unrecognized token",
"errorpos": 2
"tokenize": "a ?"}, ] }
}
Error responses
Code Reason
400 BAD REQUEST "Syntax of request could not be understood by the server."
415 UNSUPPORTED MEDIA TYPE "Unsupported content-encoding of [encoding type]"
Example JSON request
payload = {"action": {"name": "getlast"}
headers = {"content-type": "application/json"}
response = requests.post("/exceptions", data=json.dumps(payload), headers=headers)
Example browser request
http://localhost:8001/tokenizer?action.tokenize=point%201