Change Request: Standardize OperationId's of paths in OpenApi definitions of FSPIOP API.
kleyow opened this issue · comments
Open API for FSP Interoperability - Change Request
Table of Contents
1. Preface
___This section contains basic information regarding the change request.
1.1 Change Request Information
| ___ | ___ |
|---|---|
| Requested By | Kevin Leyow, Modusbox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date |
2. Problem Description
___2.1 Background
The OpenApi definitions of v1.0 and v1.1 of the FSPIOP Specification has no standard naming scheme for operationID's. OperationID's are important for some framworks when routing paths. Some microservices deviate from the hosted definition
2.2 Current Behaviour
Current definition has no standardized naming scheme for operation Id's
Example
put:
description: The callback `PUT /participants/{Type}/{ID}` (or `PUT /participants/{Type}/{ID}/{SubId}`) is used to inform the client of a successful result of the lookup, creation, or deletion of the FSP information related to the Party. If the FSP information is deleted, the fspId element should be empty; otherwise the element should include the FSP information for the Party.
summary: Return participant information
tags:
- participants
operationId: ParticipantsByTypeAndID3
^ No HTTP verb. Not very descriptive post:
description: The HTTP request `POST /participants/{Type}/{ID}` (or `POST /participants/{Type}/{ID}/{SubId}`) is used to create information in the server regarding the provided identity, defined by `{Type}`, `{ID}`, and optionally `{SubId}` (for example, `POST /participants/MSISDN/123456789` or `POST /participants/BUSINESS/shoecompany/employee1`). An ExtensionList element has been added to this reqeust in version v1.1
summary: Create participant information
tags:
- participants
operationId: ParticipantsSubIdByTypeAndIDPost
^ Example of a descriptive name. Describes path. Uses HTTP verb. 2.3 Requested Behaviour
Operation Id's are updated.
3. Proposed Solution Options
___Decide on naming scheme and update documents.
Thanks @kleyow!
2 questions come to mind:
- What should the naming conventions be?
- What will the impact of this change be? Both from external parties using the API, and also the Mojaloop Implementation?
What should the naming conventions be?
After researching a bit. Here are two suggestions in my descending preference.
If neither satisfy I can do some more research as to what would be best for fspiop.
Seems there's no universal standard.
More pragmatic version similar to what we are using. Could get verbose with long paths.
example. camelCase
{HTTPVerb} {Resource} By {Param} {Param} {Param}...etc {HTTPVerb}
/participants/{Type}/{ID}/{SubId}/error
putParticipantsByTypeIDSubIdError or participantsByTypeIDSubIdErrorPut
More descriptive human readable Id.
GET a single Model: getModel
GET a list of Model: listModels
POST a new Model: createModel or addModel
PUT a callback to a Model: notifyModel
example
/participants/{Type}/{ID}/{SubId}/error
notifyParticipantsByTypeIDSubIdError
What will the impact of this change be? Both from external parties using the API, and also the Mojaloop Implementation?
For internal Mojaloop development
- For services that are still using hapi, nothing should need to be done other than syncing the ID's for sanity sake.
- For services using frameworks that count on the OperationId to handle routes it would result in having to update their local definition and route definitions. Nothing should break, more so just updating definitions for consistency across services.
For external parties it should be a nice to have at best. Minimal impact since their code is based off their own local openapi definition they can still use whatever OperationId they want. I believe.
I think this suggestion is great @kleyow!
Direct Comments:
- For services that are still using hapi, nothing should need to be done other than syncing the ID's for sanity sake.
Note: We would still need to update the operationIds in the swagger implementations
In General:
I would take this a step further, generalise this and extend it to all our APIs.
For example on FSPIOP PUT operations are akin to a notification as you infer above.
But in the Admin API, the PUT is a classic "update" operation, and thus I would add this to the "general" list:
- PUT to an existing Model: updateModel
Edge Cases:
There is another point on the FSPIOP API that we would need to address here: specifically, the "PATCH" operation added in FSPOP v1.1 --> https://github.com/mojaloop/mojaloop-specification/blob/master/documents/v1.1-document-set/fspiop-v1.1-openapi2.yaml#L1818
PATCH callback to a Model: updateNotifyModel <-- @kleyow, @elnyry-sam-k: do you have a better suggestion here?
In this kind of situation, I do feel that it starts to get ugly and thus it may be cleaner to stick to HTTP Methods as the prefix instead. However, this would then require the user to infer the semantics of the method based on the context (i.e. FSPIOP vs Admin API).
Example:
GET a single Model: getModel
GET a list of Model: getModels <-- note the "s" suffix to indicate that many are possibly returned
POST a new Model: postModel
PUT a callback to a Model: putModel
PATCH callback to a Model: patchModel
I don't have a problem with either naming approach, but I do feel that the later is simpler.
Thanks for the issue @kleyow and the comments @lewisdaly and @mdebarros ...
So @kleyow, in our context, what are the frameworks that are using operationIDs? Even though this is a definite nice to have, we need to validate if this is a requirement at this stage or a standardization for future purposes.
Also, as some of you have stated, wanted to put this here for anyone concerned - this change doesn't affect any existing or current implementations and should be non-breaking because the current implementations wouldn't have relied on these (operation IDs) anyway..
@elnyry-sam-k openapi-backend is one that is currently in our stack.
https://github.com/mojaloop/transaction-requests-service/search?q=TransactionRequestsByID
Here you can see an example of handlers having to be correlated to an OperationId.
Ok, thanks for that Kevin. lets setup some time to go over these.