5GC_APIs
5GC_APIs copied to clipboard
Link between OpenAPI operation identifiers and 3GPP services
First, thanks for providing this up-to-date repository !
I am trying to match the defined operations from the OpenAPI definitions to the 3GPP functional services definitions. In some yaml file, the keyword operationId
seems well used, as in TS29518_Namf_Communication.yaml.
However, in some other yaml files, this looks completely messed up, as in TS29508_Nsmf_EventExposure.yaml, where 4 operations have the following ids: CreateIndividualSubcription
, DeleteIndividualSubcription
, GetIndividualSubcription
and ReplaceIndividualSubcription
; but the TS 23.502 and TS 29.508 define the 4 following service operations: Subscribe
, Unsubscribe
, Notify
and AppRelocationInfo
, where the 2 last correspond in the yaml file to callbacks without operationId
actually set...
Do you know if there is an intention to have this made more reliable during the next 3GPP meetings, or if this operationId
keyword is just cosmetic and will never match perfectly the 3GPP service definitions ?
Hi @p1-bmu, thanks for sharing your feedback!
The operationId
attributes have been assigned in most APIs with no actual linking to the "stage-2" specs (e.g. TS 23.502).
They have been following an approach to be simply descriptive strings identifying uniquely each operation (mainly to be used by tools/libraries as indicated in the OpenAPI spec, but also where they might potentially be used along with Link objects in some APIs).
In any case, it is true that there are APIs where this info is missing, in parcitular in callback operations, and yes, there is an intention to make the appropriate corrections in coming meetings.
Thank you for your quick feedback.
As I understand, there is the intention that have systematic / explicit operationId set for most of the operations, but those ids may not match with service operations naming used in 3GPP TS (such as those defined in TS23.502, e.g. in section 5.2).
Aside from this, I noted that 2 operations may have the same operationId, whereas the OpenAPI specification suggests those operationId to uniquely identify a single operation (these IDs must be unique among all operations described in your API):
- TS29551_Nnef_PFDmanagement.yaml, operationId
Nnef_PFDmanagement_Fetch
identifies multiple operations:- ('/applications', 'get')
- ('/applications/{appId}', 'get')
- TS29551_Nnef_PFDmanagement.yaml, operationId
Nnef_PFDmanagement_Subscribe
identifies multiple operations:- ('/subscriptions', 'post')
- ('/subscriptions/{subscriptionId}', 'put')
- TS29518_Namf_Communication.yaml, operationId
N2InfoNotify
identifies multiple operations:- ('/ue-contexts/{ueContextId}', 'put', 'callbacks', 'onN2MessageNotify', '{$request.body#/n2NotifyUri}', 'post')
- ('/ue-contexts/{ueContextId}/n1-n2-messages/subscriptions', 'post', 'callbacks', 'onN1N2MessageNotify', '{$request.body#/n2NotifyCallbackUri}', 'post')
I'll let you close the issue if you want, as your initial answer was fine to me. But maybe you want to keep it open to track it further.
I think it's better to keep it open, as you said, for easier tracking and as a reminder for me to trigger the corresponding corrections at next 3GPP meeting :)