Change Request: (WIP) Admin API identifier usage is unclear

[Miguel de Barros]

Open API for FSP Interoperability - Change Request

Table of Contents

• 1. Preface
  • 1.1 Change Request Information
  • 1.2 Document Version Information
• 2. Problem Description
  • 2.1 Background
  • 2.2 Current Behaviour
  • 2.3 Requested Behaviour
• 3 Proposed Solution Options

1. Preface

___

1.1 Change Request Information

Info	Details
Requested By	Miguel de Barros, ModusBox
Change Request Status	In review ☒ / Approved ☐ / Rejected ☐
Approved/Rejected Date

1.2 Document Version Information

Version	Date	Author	Change Description
1.0	2021-08-23	Miguel de Barros	Initial version.

2. Problem Description

___

2.1 Background

The Admin API schemas definition for the Participant contains two Identifiers, the name, and an id as follows:

Participant:
  title: Participant
  type: object
  properties:
    name:
      description: The name of the participant.
      type: string
      example: hub
    id:
      description: The identifier of the participant in the form of a fully qualified domain name combined with the participant's `fspId`.
      type: string
      example: dev1-central-ledger.mojaloop.live/participants/hub

There is some confusion between the two. In a traditional REST context, one would expect to use the id to interact with Admin API's operations, however, the name is actually used for this purpose.

2.2 Current Behaviour

The name is the functional identifier and is used for all Admin API operations such as the GET /participants/{name}.

However, I am uncertain as to the use & requirements for the id as I am not aware of any Hub implementor, FSPs or Mojaloop Services that utilise this Fully Qualified Domain Name (FQDN).

Example of the Admin API GET /participants response:

[
  {
    "name": "hub",
    "id": "dev1-central-ledger.mojaloop.live/participants/hub", <-- FQDN Identifier
    "created": "2021-01-12T10:56:30.000Z",
    "isActive": 0,
    "links": {
      "self": "dev1-central-ledger.mojaloop.live/participants/hub"
    },
    "accounts": [
      {
        "id": 1,
        "ledgerAccountType": "POSITION",
        "currency": "AED",
        "isActive": 0,
        "createdDate": "2021-01-12T10:56:30.000Z",
        "createdBy": "unknown"
      }
    ]
  }
]

2.3 Requested Behaviour

To be discussed

3. Proposed Solution Options

To be discussed

• No change, i.e. keep the identifier as the FQDN
• Remove the identifier as there is no apparent use for it
• Modify the identifier to return the Datastore Identifier <-- this aligns with the Settlement API, and the existing CR [mojaloop/specification/#91](https://github.com/mojaloop/mojaloop-specification/issues/910

[Lewis Daly]

Thanks for this Miguel. I've had similar confusions about the ids and names in the Admin API.

Before we discuss the options here, perhaps we should use the term "Unique Identifier" instead of "Datastore identifier". I'm concerned that the underlying choice of database, or database concepts have crept into this API design.

Now, to the id and name issue:

In my ideal world, I think our API should have:

1. A human-readable name for a participant to present to real humans accessing UI elements.
2. A machine-readable identifier for API interactions with that participant (what we are currently using name for). who creates this identifier would be up for debate, but I think it should be either the DFSP or Hub operator, not the Database.

As for the FQDN id, my preference would be to change this field to be a string ID field, but that would be a breaking change.

Perhaps to side-step breaking changes, we could support 2 new fields:

• pid - A participantId string with no special characters, spaces, etc.
• publicName - A human readable name