Partner News

In this service platform, every NF can expose services and consume services provided by other NF. Since NFs are loosely coupled and interfaced with APIs, they can be easily deployed anywhere, on demand, without impact on the existing ones. New services or service instances are published in a centralized repository – the Network Repository Function (NRF) – accessible to all the NFs to discover the services available in the network and retrieve required routing information to interact with the NFs supporting the services.

These services can also be made open to third-party applications through a dedicated NF, the Network Exposure Function (NEF). The NEF exposes secured APIs to external or internal applications for a robust but easy access to the core network services and capabilities supported by the NFs.

The adoption of the SBA with APIs exposing services has contributed to migrate the mobile core network, traditionally conceived as a walled garden relying on telco-specific point-to-point protocols (e.g., Diameter), to a scalable, resilient and extensible service-oriented environment, more open to third-party developers and vertical industries for the creation of on-demand tailored services.

Design principles and documentation guidelines for 3GPP RESTful APIs

In order to speed up and ease the development of new APIs while ensuring reusability and interworking with existing ones, 3GPP has specified in 3GPP TS 29.501 a set of design principles and documentation guidelines for the specifications of the APIs used over SBIs. This set of recommendations is not restricted to SBIs but is also pertinent for any API defined by 3GPP, including northbound APIs, APIs used for 3rd party exposure, management/orchestration, charging or media streaming. The aim of 3GPP TS 29.501 is to provide an overall consistency at the 3GPP level for the design and description of the different APIs.

The main principle for the design of 3GPP API can be simply summarized as follows: API should be designed as RESTful API whenever possible.

REST (REpresentational State Transfer) is an architectural style that imposes certain guiding principles (or constraints) to be satisfied by an API to be referred to as RESTful API. In short, the underlying server implementation is hidden by a layer of abstraction: service data are defined as "resource" uniquely identified by URI (Uniform Resource Identifier) and service consumers use HTTP methods to access to only a representation of resources. The representation can be delivered over HTTP using different file formats, JSON being the most popular one.

For basic Create, Read, Update, and Delete (CRUD) operations on resource/service data, standard HTTP/2 methods (e.g. GET, POST, PUT, DELETE) are used to operate on resources uniquely identified by URIs.

The recommendation for the design of RESTful API is not blindly enforced as a dogma. When the REST model is not applicable (e.g. for non-CRUD operations), service operations can be however implemented as custom operations. Instead of operating on a resource, a POST operation can be used to call a specific function to execute in the NF service provider and the result of the function is provided to the NF service consumer in the response. And of course, depending on the service requirements, it is possible to mix REST-style operations and custom operations in the same API.

Along the recommendation for the design of RESTful API, 3GPP TS 29.501 also documents recommended best practices for API designers on (non-exhaustive list):

• Use of the HTTP methods (e.g. standards compliance, adherence to industry best-practices, homogeneity across different APIs, etc.)
• Error handling and use of HTTP response codes
• API versioning and version control
• Resource URI structure
• Resource representation (e.g. using the JavaScript Object Notation (JSON) format) and content format negotiation
• Naming conventions

For further information, please refer to 3GPP TS 29.501.

API description exposure through OpenAPI specification

3GPP selected OpenAPI version 3 (formerly known as Swagger) as the formal language to be used for the definition of APIs in the Service-Based Architecture.

As indicated in 3GPP TS 29.501, each API is documented in a 3GPP technical specification (TS) that describes in natural language the API, and this specification also includes a normative Annex containing an OpenAPI description of the API.

An OpenAPI description defines a standard, programming language-agnostic interface specification for HTTP APIs, which allows both humans and computers to discover and understand how an API works without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

The OpenAPI document provides an easy description of the API, including:

• Available resources and authorized operations on each resource
• Operation parameters Input and output for each operation
• Authentication methods
• Contact information, license, terms of use and other information.

While OpenAPI descriptions can also be written in JSON, YAML is the preferred format recommended by 3GPP TS 29.501. Using a single format provides uniformity and allow reusability of OpenAPI specifications. Reusability is an important aspect to speed up the development of new APIs. Components of an OpenAPI specifications (parameters, response, data type, etc.) can be simply imported into another specification by simply referencing the OpenAPI description defining these components.

Storage of OpenAPI specification files in 3GPP Forge

OpenAPI descriptions are extracted from the annex of the 3GPP Technical Specifications and made available as stand-alone YAML files, identified by a file name composed of the API name prefixed by the TS number of the specification containing the OpenAPI description. All these files are then stored in a common repository managed by Gitlab on the 3GPP Forge, a web-based collaborative software platform managed by 3GPP for both developing and sharing applications.

This common repository allows:

• A centralized and unified handling of all the OpenAPI descriptions developed by 3GPP
• A validation process based on tools common to all the working groups
• An easier cross-referencing of OpenAPI descriptions for components reusability
• External users to have a unique location where to find and download all the OpenAPI descriptions produced by 3GPP for testing and implementation purposes.

With GitLab, the syntax of OpenAPI specifications is automatically checked, using built-in and specific testing tools developed by 3GPP experts. The version control mechanism allows to track the history of changes. Multiple branches are managed in parallel, each branch having different access control permissions:

• One stable branch per release containing the set of OpenAPI specifications approved by TSG for this release.
• One temporary branch per release containing the set of OpenAPI specifications drafted by the working groups and sent for approval at the parent TSG.
• Additional branches can be created by working groups or delegates to test proposed changes to the OpenAPI descriptions.

Today, over 200 OpenAPI specifications are stored in the 3GPP Forge. And many more are still to come with the development of new services in the forthcoming releases.

If the use of the 3GPP Forge has significantly simplified the development of API specifications, 3GPP does not yet make the most of the Gitlab environment provided by 3GPP Forge for the handling of OpenAPI descriptions. While possible in open collaborative projects, it is still not possible to submit the proposed changes directly in 3GPP Forge and incorporate these changes into the OpenAPI specifications.

Modifications can only be done through approved Change Request (CR) against the technical specification containing the OpenAPI description. To make it possible, the 3GPP working methods would have to be first updated in order to become more agile and embrace more modern and open development practices (CI/CD, DevOps, etc.).

The GitLab repository containing OpenAPI descriptions is available at the following location: https://forge.3gpp.org/rep/all/5G_APIs.

The author wishes to acknowledge the amazing work of Jesus De Gregorio on OpenAPIs and his guidance in the production of this article.

This article first appeared in Highlights, Issue 4.