Page 11 - 3GPP_Highlights_I4

REST (REpresentational State Transfer) is an architectural While OpenAPI descriptions can also be written in JSON, YAML
style that imposes certain guiding principles (or constraints) is the preferred format recommended by 3GPP TS 29.501. Using
to be satisfied by an API to be referred to as RESTful API. In a single format provides uniformity and allow reusability of
short, the underlying server implementation is hidden by a OpenAPI specifications. Reusability is an important aspect to
layer of abstraction: service data are defined as “resource” speed up the development of new APIs. Components of an
uniquely identified by URI (Uniform Resource Identifier) OpenAPI specifications (parameters, response, data type, etc.)
and service consumers use HTTP methods to access to only can be simply imported into another specification by simply
a representation of resources. The representation can be referencing the OpenAPI description defining these components.
delivered over HTTP using different file formats, JSON being
the most popular one.
Storage of OpenAPI specification
For basic Create, Read, Update, and Delete (CRUD)
operations on resource/service data, standard HTTP/2 files in 3GPP Forge
methods (e.g. GET, POST, PUT, DELETE) are used to operate
on resources uniquely identified by URIs.
OpenAPI descriptions are extracted from the annex of the 3GPP
The recommendation for the design of RESTful API is not Technical Specifications and made available as stand-alone
blindly enforced as a dogma. When the REST model is not YAML files, identified by a file name composed of the API name
applicable (e.g. for non-CRUD operations), service operations prefixed by the TS number of the specification containing the
can be however implemented as custom operations. Instead OpenAPI description. All these files are then stored in a common
of operating on a resource, a POST operation can be used to repository managed by Gitlab on the 3GPP Forge, a web-based
call a specific function to execute in the NF service provider collaborative software platform managed by 3GPP for both
and the result of the function is provided to the NF service developing and sharing applications.
consumer in the response. And of course, depending on
the service requirements, it is possible to mix REST-style This common repository allows: A centralized and unified
operations and custom operations in the same API. handling of all the OpenAPI descriptions developed by 3GPP,
A validation process based on tools common to all the working
Along the recommendation for the design of RESTful groups, easier cross-referencing and provides external users with
API, 3GPP TS 29.501 also documents recommended best a unique location for all the OpenAPI descriptions produced by
practices for API designers on (non-exhaustive list): 3GPP for testing and implementation purposes.
• Use of the HTTP methods (e.g. standards compliance, With GitLab, the syntax of OpenAPI specifications is
adherence to industry best-practices, homogeneity automatically checked, using built-in and specific testing tools
across different APIs, etc.) developed by 3GPP experts. The version control mechanism
tracks the history of changes. Multiple branches are managed in
• Error handling and use of HTTP response codes parallel, each branch having different access control permissions
• API versioning and version control (the OpenAPI specifications approved by TSG for the release,
one temporary branch per release for specs. sent for approval at
• Resource URI structure TSG and additional branches for proposed changes to OpenAPI
descriptions).
• Resource representation (e.g. using the JavaScript
Object Notation (JSON) format) and content format 3GPP Forge (GitLab) Repository
negotiation OpenAPI descriptions TM
• Naming conventions forge.3gpp.org/rep/all/ /Rel-17 /TS29122_AsSessionWithQoS.yaml
/Rel-16
For further information, please refer to 3GPP TS 29.501. 5G_APIs /Rel-15
/TS29.510_Nnrf_AccessToken.yaml
/Rel-15-drafts-TSG#
API description exposure through /Rel-16-drafts-TSG#
OpenAPI specification Possibility for any required, additional /Rel-17-drafts-TSG#
temporary branches
(per WG meeting, per delegate,
per CR, etc.) /TS32291_Nchf_ConvergedCharging.yaml

3GPP selected OpenAPI version 3 (formerly known as Today, over 200 OpenAPI specifications are stored in the 3GPP
Swagger) as the formal language to be used for the Forge. And many more are still to come with the development of
definition of APIs in the Service-Based Architecture. new services in the forthcoming releases.
As indicated in 3GPP TS 29.501, each API is documented in If the use of the 3GPP Forge has significantly simplified the
a 3GPP technical specification (TS) that describes in natural development of API specifications, 3GPP does not yet make
language the API, and this specification also includes a the most of the Gitlab environment provided by 3GPP Forge
normative Annex containing an OpenAPI description of the for the handling of OpenAPI descriptions. While possible in
API. open collaborative projects, it is still not possible to submit the
proposed changes directly in 3GPP Forge and incorporate these
An OpenAPI description defines a standard, programming changes into the OpenAPI specifications.
language-agnostic interface specification for HTTP APIs,
which allows both humans and computers to discover and Modifications can only be done through approved Change
understand how an API works without requiring access Request (CR) against the technical specification containing the
to source code, additional documentation, or inspection OpenAPI description. To make it possible, the 3GPP working
of network traffic. When properly defined via OpenAPI, a methods would have to be first updated in order to become
consumer can understand and interact with the remote more agile and embrace more modern and open development
service with a minimal amount of implementation logic. practices (CI/CD, DevOps, etc.).
The OpenAPI document provides an easy description of The GitLab repository containing OpenAPI descriptions is
the API, including: Available resources and authorized available at the following location:
operations on each resource, Operation parameters Input https://forge.3gpp.org/rep/all/5G_APIs.
and output for each operation, Authentication methods The author wishes to acknowledge the amazing work of Jesus De
and Contact information, license, terms-of-use and other Gregorio on OpenAPIs and his guidance in the production of this
information. article.
|
Issue 04 - Ma y 2 022 11