1 Introduction
The following clauses apply, where appropriate, to all API specifications described here.
- The Service Level Agreement (SLA) must be negotiated and agreed between the RCA and the MPAI as a Service Provider prior to the subsequent use of the Server API exposed by the Service Provider.
- The application security paradigm, described by the SLA, MUST be chosen from the standard HTTP security paradigms (BASIC, DIGEST, BEARER) but is not normative.
- The example HTTP request and response messages only include essential and normative information, allowing for interoperability and subsequent derivational extensions.
- Only the relevant HTTP headers are shown. These MUST be accompanied by all HTTP headers required by the HTTP 1.1 standard and all those required to satisfy the features of the security paradigm that is employed.
- All API requests MUST use the most recent version of Transport Layer Security (TLS), and client certificate exchange MAY be necessary based on the server’s security requirements.
- The term {cid} represents the ID of a Controller Instance returned by a successful request to the Controller Instance Creation API specified below.
- The term{mid} represents the ID of a Module Instance returned by a successful request to the Workflow Instance Start API specified below.
- Any ID format may be used for all SCI and Module Instance IDs exchanged between the RCA and the HTTP Server of the MaaS. However, use of UUIDs is recommended.
- Standard HTTP status codes MUST be used to communicate eventual failure of an API request (302, 400, 401, 403, 404, 500 etc) and MUST be used in accordance with their standard meaning.
- In all API Requests, other than the initial SCI Creation Request, a value returned in the optional prefix field of the SCI Creation Response message, MUST be used in place of the default /MPAI/AIFU prefix.
2 Preparation of the infrastructure
2.1 Initialise the Controller Instance
All API Calls that are performed subsequent to the Call MUST be with respect to an SCI Identifier returned by a successful invocation of this Call.
2.1.1 REQUEST
| POST /MPAI/AIFU/Controller HTTP/1.1 ACCEPTS: application/json |
2.1.2 RESPONSE
| HTTP/1.1 201 CREATED CONTENT-TYPE: application/json CONTENT-LENGTH: <size of body>{“id”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx”} |
For enhanced security reasons, the Response returned by the Controller Initialisation Request MAY return an alternative mapping of the standard collection of MPAI AIFU route prefix to the Controller Instance specific route prefix. This route prefix mapping, if returned, MUST be used in place of the standard /MPAI/AIFU/ prefix in all subsequent Requests issued for the corresponding SCI.
HTTP/1.1 201 CREATED
CONTENT-TYPE: application/json
CONTENT-LENGTH: <size of message>
{“id”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx”, “prefix”:”/alternative/endpoint/prefix”}
2.4 Start AI Module
This operation requests the SCI to initiate the AIW. This assumes that the preceding check and upload calls would return the corresponding AIW Identifier.
3.2.4.1 REQUEST
POST /MPAI/AIFU/{cid}/AIW/Start HTTP/1.1
ACCEPTS: application/json
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
{“module”: “mymodule”}
2.4.2 RESPONSE
HTTP/1.1 200 OK
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
{
“controller”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx”,
“id”: “wwwwwwww-wwww-wwww-wwww-wwwwwwwwwwww”,
“name”: “mymodule”,
“state”: “ACTIVE”,
“change”: <date string of state change>
}
2.5 Pause AI Module
This operation requests the SCI to suspend the AIW.
2.5.1 REQUEST
GET /MPAI/AIFU/{cid}/AIW/{mid}/Pause HTTP/1.1
ACCEPTS: application/json
2.5.2 RESPONSE
HTTP/1.1 200 OK
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
{
“controller”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx”,
“id”: “wwwwwwww-wwww-wwww-wwww-wwwwwwwwwwww”,
“name”: “mymodule”,
“state”: “PAUSED”,
“change”: <date string of state change>
}
2.6 AI Module Status
This operation requests the current status of the AIW.
3.6.1 REQUEST
GET /MPAI/AIFU/{cid}/AIW/{mid} HTTP/1.1
ACCEPTS: application/json
2.6.2 RESPONSE
HTTP/1.1 200 OK
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
{
“controller”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx”,
“id”: “wwwwwwww-wwww-wwww-wwww-wwwwwwwwwwww”,
“name”: “mynodule”,
“state”: <current status>,
“change”: <date string of state change>
}
2.7 Resume AI Module
This operation requests the SCI to resume the paused AIW.
2.7.1 REQUEST
GET /MPAI/AIFU/{cid}/AIW/{mid}/Resume HTTP/1.1
ACCEPTS: application/json
2.7.2 RESPONSE
HTTP/1.1 200 OK
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
{
“controller”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx”,
“id”: “wwwwwwww-wwww-wwww-wwww-wwwwwwwwwwww”,
“name”: “mymodule”,
“state”: “ACTIVE”,
“change”: <date string of state change>
}
3 Operation of the infrastructure
Input and output data messages will be sent and received by the RCA through the SCI to and from the input and output ports of the corresponding AIW or AIM.
The data carried in the HTTP Body section of these Input and Output messages, will be formatted in strict accordance with the standard byte serialisation, corresponding to the declared type of the involved ports, exposed specifically for this purpose in the Module Description.
3.1 Send Input Data
These operations allow delivery of input data messages prepared by the RCA to the input Port(s) of the AI Module.
3.1.1 REQUEST
POST /MPAI/AIFU/{cid}/AIW/{mid}/Input/{pid} HTTP/1.1
CONTENT-TYPE: MPAI/port-data
CONTENT-LENGTH : <size of body>
<MPAI port data bytes formatted in accordance with the expected input serialisation>
3.1.2 RESPONSE
HTTP/1.1 200 OK
3.2 Receive Output Data
These operations allow reception by the RCA of data messages delivered by the output Port(s) of the AI Modules of the SCI.
3.2.1 REQUEST
GET /MPAI/AIFU/{cid}/AIW/{mid}/Output/{pid} HTTP/1.1
3.2.2 RESPONSE
HTTP/1.1 200 OK
CONTENT-TYPE: MPAI/port-data
CONTENT-LENGTH : <size of body>
<MPAI port data bytes formatted in accordance with the expected output serialisation>
4 Termination of the infrastructure
4.1 Terminate AI Module
This operation ensures release of the AI Workflow that was instantiated by the SCI.
4.1.1 REQUEST
GET /MPAI/AIFU/{cid}/AIW/{mid}/Stop HTTP/1.1
4.1.2 RESPONSE
HTTP/1.1 200 OK
4.2 Delete Remote Controller Instance
This operation ensures release of the SCI.
4.2.1 REQUEST
DELETE /MPAI/AIFU/Controller/{cid} HTTP/1.1
4.2.2 RESPONSE
HTTP/1.1 200 OK
.
