<-Verification Use Cases   Go to ToC    Reference Software->

1 Introduction

The MMM-API is a collection of endpoints and objects supporting the execution of the thirty Process Actions performed by Processes on Items or other Processes.

The API is organised in two layers:

  1. The Process Action layer, one endpoint per Process Action, grouped by the ten Services of Table 2 of the Process Actions chapter. This is the layer through which an M-Instance is operated.
  2. The Item layer, which provides read access to Items and to their Capabilities. It is read-only: an Item is created, altered, or withdrawn only by a Process Action. In particular, Rights are not written directly – they are granted by a Service performing a Process Action, and changed only by Rights Change.

2 Description

The base path is /api/v2.2. The documentation relies on the OpenAPI 3.1.0 specification and is structured as follows.

Section Description
openapi OpenAPI version used for the documentation.
info Metadata about the API (title, version, description, contact info).
paths Endpoints and operations.
components Reusable objects: schemas, responses, parameters, security schemes.

The comprehensive list of paths and components is available in JSON format at
https://schemas.mpai.community/MMM4/V2.2/api/MMM-API.json.

Every Process Action request carries an Idempotency-Key header. A Process Action mints Items with new Identifiers and may move Value between Wallets, so a retried request must not be performed twice; replaying a key returns the original response. Requests are authenticated with a bearer token bound to the calling ProcessID, which the M-Instance resolves to a Process in order to evaluate its Rights.

3 Components

Component schemas reference the MMM-TEC V2.2 JSON Schemas at
https://schemas.mpai.community/MMM4/V2.2/data/ rather than restating them, so that the API cannot drift from the Items chapter. Four schemas are specific to the API:

Schema Description
ProcessActionRequest Source ProcessID, deontic verb (May, May Not, Must), Action, and Complements.
Complements Nil, At, From, To, Of, and a With array, in the order given by the Backus Naur Form.
ProcessActionResponse Destination ProcessID, Complements, and PA Status.
StatusedRef Reference to a Rights, Transaction, or Service Pricing Model Item together with its Model or Final status.

StatusedRef is what makes the two-phase commit of MMM-TEC V2.2 visible on the wire. A Request carries the Item at Status=Model; the Response returns it at Status=Final. Neither V2.0 nor V2.1 could express this.

4 Process Action paths

Each Process Action is a POST to its own endpoint. The request body is a Process Action Request and the response body is a Process Action Response carrying the PA Status.

Service Endpoint Process Action
Communicate POST /api/v2.2/communicate/mm-send MM-Send
POST /api/v2.2/communicate/resolve Resolve
Economy POST /api/v2.2/economy/license License
POST /api/v2.2/economy/post Post
POST /api/v2.2/economy/transact Transact
Execute POST /api/v2.2/execute/execute Execute
Export POST /api/v2.2/export/mu-actuate MU-Actuate
POST /api/v2.2/export/mu-add MU-Add
POST /api/v2.2/export/mu-animate MU-Animate
POST /api/v2.2/export/mu-move MU-Move
POST /api/v2.2/export/mu-send MU-Send
Identity Manage POST /api/v2.2/identity/hide Hide
POST /api/v2.2/identity/identify Identify
POST /api/v2.2/identity/modify Modify
POST /api/v2.2/identity/register Register
Import POST /api/v2.2/import/um-actuate UM-Actuate
POST /api/v2.2/import/um-capture UM-Capture
POST /api/v2.2/import/um-send UM-Send
Information POST /api/v2.2/information/authenticate Authenticate
POST /api/v2.2/information/discover Discover
POST /api/v2.2/information/interpret Interpret
Item Manage POST /api/v2.2/item/author Author
POST /api/v2.2/item/convert Convert
Locate POST /api/v2.2/locate/mm-add MM-Add
POST /api/v2.2/locate/mm-animate MM-Animate
POST /api/v2.2/locate/mm-capture MM-Capture
POST /api/v2.2/locate/mm-move MM-Move
POST /api/v2.2/locate/property-change Property Change
Rights Manage POST /api/v2.2/rights/rights-change Rights Change
POST /api/v2.2/rights/validate Validate

4.1 PA Status and HTTP status codes

The PA Status is always present in the response body. It is additionally mapped onto HTTP status codes so that a client may act without parsing the body.

HTTP Meaning
200 / 201 The Process Action was performed. PA Status is Ack. 201 when a new Item was minted.
402 The Service is a pay Service for this Process Action. See 4.2.
403 The requesting Process does not hold the Rights required.
404 Unknown Item or Process.
409 The Process Action conflicts with the current state of the Item.
415 The destination Process does not support the Item’s Qualifier.
422 The Request is well formed but the Process Action could not be performed.

403 and 415 are the two failure causes named by the Processes chapter, and each has a
remedy inside the API. On 415 the client may request Item Manage/convert, or
delegate the Process Action to another Process over the Inter-Process Protocol. On 403 the
client may seek a Rights Change.

4.2 Pay Services: the Model to Final protocol

Any Service may charge for a Process Action. The exchange is three calls. The first Request carries the Service Pricing Model at Status=Model and is answered with 402 and a Transaction at Status=Model. The client settles that Transaction. The original Request is then resubmitted with the Transaction at Status=Final, and the Service performs the Process Action and returns Rights at Status=Final.

POST /api/v2.2/economy/post
Idempotency-Key: 5f3c...
{ "sourceProcessID": "Seller",
  "deonticVerb": "May",
  "action": "Post",
  "complements": { "Nil": "AssetID", "To": "POSrvc",
                   "With": [ { "itemID": "Post_Rights",  "status": "Model" },
                             { "itemID": "SPM",          "status": "Model" } ] } }

402 Payment Required
{ "servicePricingModel": { "itemID": "SPM", "status": "Model" },
  "transaction":         { "itemID": "PostingFee_Transaction", "status": "Model" } }
POST /api/v2.2/economy/transact
{ "sourceProcessID": "Seller", "deonticVerb": "May", "action": "Transact",
  "complements": { "With": [ { "itemID": "PostingFee_Transaction", "status": "Model" } ] } }

200 OK
{ "destinationProcessID": "TRSrvc",
  "complements": { "With": [ { "itemID": "PostingFee_Transaction", "status": "Final" } ] },
  "paStatus": { "code": "Ack" } }
POST /api/v2.2/economy/post
Idempotency-Key: 5f3c...
{ "sourceProcessID": "Seller", "deonticVerb": "May", "action": "Post",
  "complements": { "Nil": "AssetID", "To": "POSrvc",
                   "With": [ { "itemID": "Post_Rights", "status": "Model" },
                             { "itemID": "PostingFee_Transaction", "status": "Final" } ] } }

201 Created
{ "destinationProcessID": "POSrvc",
  "complements": { "With": [ { "itemID": "SPM",         "status": "Final" },
                             { "itemID": "Post_Rights", "status": "Final" } ] },
  "paStatus": { "code": "Ack" } }

4.3 Sample Process Action

MM-Add places an Item at an M-Location with a Spatial Attitude.

curl -X POST 'https://localhost:7099/api/v2.2/locate/mm-add' \
  -H 'Authorization: Bearer <token bound to the calling ProcessID>' \
  -H 'Idempotency-Key: 9c21...' \
  -H 'Content-Type: application/json' \
  -d '{ "sourceProcessID": "Friend1",
        "deonticVerb": "May",
        "action": "MM-Add",
        "complements": { "Nil": "Persona1ID", "At": "MVS",
                         "With": [ "SA",
                                   { "itemID": "Persona1_Rights", "status": "Model" } ] } }'
201 Created
{ "destinationProcessID": "LCSrvc",
  "complements": { "With": [ { "itemID": "Persona1_Rights", "status": "Final" } ] },
  "paStatus": { "code": "Ack" } }

5 Item and Capabilities paths

Endpoint Description
GET /api/v2.2/items List Items, optionally filtered by the Data Type acronym of Table 1 of the Items chapter.
GET /api/v2.2/items/{itemID} Retrieve an Item, subject to the Rights of the calling Process.
GET /api/v2.2/items/{itemID}/rights Item Capabilities: the Processes holding Rights on the Item, and which Rights.
GET /api/v2.2/processes/{processID}/rights Rights held by a Process.
GET /api/v2.2/processes/{processID}/capabilities Process Capabilities: performable Actions, supported Items and Qualifiers, Rights held.
GET /api/v2.2/m-instance/capabilities M-Instance Capabilities: Profile, supported Actions, Items and Qualifiers, applicable Rules.

The M-Instance Capabilities endpoint is what allows a client to establish, before issuing a Request, which Profile the M-Instance implements and which Qualifiers it supports. Without it the convert-or-delegate remedy of clause 4.1 cannot be planned.

6 Changes from the V2.0 API

V2.0 V2.2
Eleven Services chosen ad hoc. Ten Services, matching Table 2 of the Process Actions chapter.
Process Actions memorised at POST /api/Activity/process-actions. Thirty Process Action endpoints that perform the Action.
Items written directly through CRUD. Item layer read-only; Items change only by Process Action.
Rights created and updated through CRUD. Rights granted by a Service and changed by Rights Change.
No Export or Import endpoints. UM-Capture, UM-Actuate, UM-Send and the five MU-* Process Actions.
No Execute, Interpret, Validate, or License endpoints. All four present.
No Service Pricing Model, no Model/Final status. 402 pay-Service protocol and StatusedRef on every Rights and Transaction.
No Capabilities endpoint. M-Instance, Process, and Item Capabilities.
No authentication, no idempotency. Bearer token bound to ProcessID; Idempotency-Key required.
/api/Location/mlocations. Removed: M-Location is now MPAI-OSD Location Object.
/api/Conversion/basic-objects/{id}. Replaced by /api/v2.2/item/convert, taking any Item and a target Qualifier.

 

<-Verification Use Cases   Go to ToC    Reference Software->