<- Data Types     Go to ToC    Reference Software ->

1 Introduction
2 Preparation of the infrastructure
2.1 Initialise the Controller Instance
2.2 Start AI Module
2.3 Pause AI Module
2.4 AI Module Status
2.5 Resume AI Module
3 Operation of the infrastructure
3.1 Send Input Data
3.2 Receive Output Data
3.3 Bouts
3.3.1 Open Bout
3.3.2 Get Bout
3.3.3 Close Bout
3.3.4 Give Bout
3.3.5 End Bout
3.3.6 Refusals
4 Termination of the infrastructure
4.1 Terminate AI Module
4.2 Delete Remote Controller Instance

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 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}

2.2      Start AI Module

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>

}

2.3      Pause AI Module

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>

}

2.4      AI Module Status

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>

}

2.5      Resume AI Module

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).

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}/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

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}/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>

3.3 Bouts

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 Open Bout

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.

3.3.2 Get Bout

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.

3.3.3 Close Bout

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.

3.3.4 Give Bout

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

3.3.5 End Bout

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.

3.3.6 Refusals

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

4.1      Terminate AI Module

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 ->