Change Request: Standardize OperationId's of paths in OpenApi definitions of FSPIOP API. about mojaloop-specification HOT 6 OPEN

Ok, thanks for that Kevin. lets setup some time to go over these.

from mojaloop-specification.

Thanks @kleyow!

2 questions come to mind:

1. What should the naming conventions be?
2. What will the impact of this change be? Both from external parties using the API, and also the Mojaloop Implementation?

from mojaloop-specification.

@lewisdaly

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.

from mojaloop-specification.

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.

from mojaloop-specification.

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

from mojaloop-specification.

@elnyry-sam-k openapi-backend is one that is currently in our stack.

https://github.com/mojaloop/transaction-requests-service/blob/f09222f57aaf547df48ac563d2261e84515cec9a/src/handlers/index.js#L41

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.

from mojaloop-specification.