<- Data Types Go to ToC Reference Software ->
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 key words MUST, MUST NOT, SHOULD and MAY are to be interpreted as described in RFC 2119 and RFC 8174.
- 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 Module Start API specified below.
- The terms {DataType} and {PortNumber} together identify a boundary Port of the Module. They are two consecutive segments of the path of the request URL (RFC 3986), {DataType} first, separated by /:
- {DataType} is the Data Type of the Port expressed in canonical form: its Header, <Standard>-<Acronym>-V<Major>.<Minor>, matching the regular expression ^[A-Z0-9]{3,4}-[A-Z0-9]{3}-V[0-9]{1,2}\.[0-9]{1,2}$, or a type of the type system of MPAI-AIF (Metadata 1.1), such as string;
- {PortNumber} is the Port Number of the Port: a decimal integer from 1, with no leading zero, matching the regular expression ^[1-9][0-9]*$. It is always present; it is 1 where the AIM Description gives no Port Number for the Port.
A struct or variant type of the type system of MPAI-AIF is percent-encoded (RFC 3986); no other segment contains a character that needs percent-encoding. A path under /Input/ names an input Port, one under /Output/ an output Port. The SCI MUST refuse with 404 a request whose {DataType} or {PortNumber} does not have this form or that names no boundary Port of the Module in that direction. The form <DataType>#<PortNumber> of MPAI-AIF is used where a Port is named outside a URL, as in the Binding of a Bout, and MUST NOT be used in a request URL, where # begins a fragment.
- 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”}
An RCA that will give Bouts on input Ports (3.3.4) MUST send, as body of the Request (CONTENT-TYPE: application/json), {“Proof”: proof}, where proof is its Cryptographic Instance Identity (PTF-CII), whose CryptographicInstanceTime is fresh. The SCI MUST verify its Integrity – the Signature made with the key it names – and that its CryptographicInstanceTime is fresh, MUST refuse the Request with 401 where either fails, and MUST return in the Response, as “credential”, the Instance Credential (MPAI-PTF) it issues to the RCA, valid until the SCI is deleted (4.2).
The Response MUST also return, as “anchor”, the Trust Anchor (PTF-TRA) of the Controller of the SCI. With its public key the RCA verifies the Bouts the SCI gives on output Ports (3.3) and the Instance Credential the SCI issues. The RCA MUST accept the Trust Anchor only from the Response to this Request, over its TLS connection.
HTTP/1.1 201 CREATED
CONTENT-TYPE: application/json
CONTENT-LENGTH: <size of body>
{“id”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx”, “anchor”: Trust Anchor, “credential”: Instance Credential, where a proof was sent}
This operation requests the SCI to initiate the MODULE. This assumes that the preceding check and upload calls would return the corresponding MODULE Identifier.
2.2.1 REQUEST
POST /MPAI/AIFU/{cid}/MODULE/Start HTTP/1.1
ACCEPTS: application/json
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
{“module”: “mymodule”}
2.2.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>
}
This operation requests the SCI to suspend the MODULE.
2.3.1 REQUEST
GET /MPAI/AIFU/{cid}/MODULE/{mid}/Pause HTTP/1.1
ACCEPTS: application/json
2.3.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>
}
This operation requests the current status of the MODULE.
2.4.1 REQUEST
GET /MPAI/AIFU/{cid}/MODULE/{mid} HTTP/1.1
ACCEPTS: application/json
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”: “mynodule”,
“state”: <current status>,
“change”: <date string of state change>
}
This operation requests the SCI to resume the paused MODULE.
2.5.1 REQUEST
GET /MPAI/AIFU/{cid}/MODULE/{mid}/Resume 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”: “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 MODULE or AIM.
The data carried in the HTTP Body section of these Input and Output messages is a native JSON object or compressed JSON object as specified by MPAI-AIF of the Port of the Module: CONTENT-TYPE application/json for a native JSON object, application/zstd for a compressed JSON object (3.3).
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}/MODULE/{mid}/Input/{DataType}/{PortNumber} HTTP/1.1
CONTENT-TYPE: application/json or application/zstd
CONTENT-LENGTH : <size of body>
<native JSON object or compressed JSON object as specified by MPAI-AIF of the Port of the Module>
3.1.2 RESPONSE
HTTP/1.1 200 OK
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}/MODULE/{mid}/Output/{DataType}/{PortNumber} HTTP/1.1
3.2.2 RESPONSE
HTTP/1.1 200 OK
CONTENT-TYPE: application/json or application/zstd
CONTENT-LENGTH : <size of body>
<native JSON object or compressed JSON object as specified by MPAI-AIF of the Port of the Module>
These operations let the RCA have the Messages of an output Port of the Module given as a Bout (MPAI-AIF, Communication 9.1). While a Bout is in force on the Port, Receive Output Data returns Bout Instances with CONTENT-TYPE application/zstd (RFC 8878); the RCA MUST check each as MPAI-AIF specifies for a User Agent before it uses it, and MUST NOT use an instance that fails a check. The SCI MUST give the Bout before its first Bout Instance. A Port whose AIM Description states no Bout is not given as a Bout: the request returns 409.
An RCA that holds an Instance Credential of the SCI (2.1) may also give the Messages of an input Port as a Bout (3.3.4 and 3.3.5).
3.3.1.1 REQUEST
POST /MPAI/AIFU/{cid}/MODULE/{mid}/Output/{DataType}/{PortNumber}/Bout HTTP/1.1
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
{“SigningMode”: “EachInstance”} or {“SigningMode”: “Chain”, “ChainInterval”: N}
3.3.1.2 RESPONSE
HTTP/1.1 201 CREATED
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
The Bout (AIF-BOU-V3.0), signed by the Controller of the SCI.
Returns the Bout in force on the Port, for an RCA that does not hold it.
3.3.2.1 REQUEST
GET /MPAI/AIFU/{cid}/MODULE/{mid}/Output/{DataType}/{PortNumber}/Bout HTTP/1.1
ACCEPTS: application/json
3.3.2.2 RESPONSE
HTTP/1.1 200 OK
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
The Bout in force; 404 where none is.
Closes the Bout in force on the Port: the SCI gives the CloseBout Trust Message (MPAI-PTF), and Receive Output Data returns full Messages again.
3.3.3.1 REQUEST
DELETE /MPAI/AIFU/{cid}/MODULE/{mid}/Output/{DataType}/{PortNumber}/Bout HTTP/1.1
3.3.3.2 RESPONSE
HTTP/1.1 200 OK
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
The CloseBout Trust Message; 404 where no Bout is in force.
Gives the SCI a Bout for an input Port, made and signed by the RCA with the key of its Instance Credential (2.1). The SCI MUST accept it as MPAI-PTF specifies (AcceptBout) before it takes Bout Instances of it. While it is in force, Send Input Data takes Bout Instances with CONTENT-TYPE application/zstd, which the SCI MUST check as MPAI-AIF specifies before the Module reads them.
3.3.4.1 REQUEST
POST /MPAI/AIFU/{cid}/MODULE/{mid}/Input/{DataType}/{PortNumber}/Bout HTTP/1.1
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
The Bout (AIF-BOU-V3.0), signed by the RCA.
3.3.4.2 RESPONSE
HTTP/1.1 201 CREATED
Ends the Bout that the RCA gives on an input Port: Send Input Data takes full Messages again.
3.3.5.1 REQUEST
POST /MPAI/AIFU/{cid}/MODULE/{mid}/Input/{DataType}/{PortNumber}/Bout/Close HTTP/1.1
CONTENT-TYPE: application/json
CONTENT-LENGTH : <size of body>
The CloseBout Trust Message (MPAI-PTF), signed by the RCA.
3.3.5.2 RESPONSE
HTTP/1.1 200 OK; 404 where no Bout is in force.
A refusal returns a standard HTTP status code (RFC 9110) and, as body (application/json), the MPAI-PTF Error Code of the check that failed: 404 where no Bout is in force; 409 where the Port may not be given as a Bout; 415 where the RCA does not accept application/zstd; 401 where the RCA gives a Bout and holds no valid Instance Credential of the SCI; 422 where the SCI refuses a Bout it is given (MPAI-PTF AcceptBout).
4 Termination of the infrastructure
This operation ensures release of the Module that was instantiated by the SCI.
4.1.1 REQUEST
GET /MPAI/AIFU/{cid}/MODULE/{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. The Instance Credential issued to the RCA (2.1) is revoked, and the Bouts the RCA gives are closed.
4.2.1 REQUEST
DELETE /MPAI/AIFU/Controller/{cid} HTTP/1.1
4.2.2 RESPONSE
HTTP/1.1 200 OK
<- Data Types Go to ToC Reference Software ->