# 5G Core RESTful APIs

## Summary


The 5G Core separates the control plane from the user plane. The control plane is a designed as a set of Network Functions (NFs). Each NF exposes one or more services. Each service offers one or more operations, implemented as RESTful APIs over HTTPS. For this reason, NFs are said to use Service-Based Interfaces (SBIs). 

Disaggregating the 5G Core as independent (but interworking) NFs gives Communication Service Providers (CSPs) the ability to mix and match NFs from various software vendors. Benefits include automation, cost reduction, customization, and less vendor lock-in. 

3GPP has defined these APIs in conformance with the OpenAPI Specification. APIs have been published as YAML files. Using OpenAPI tools, developers can autogenerate client/server code from these YAML files. Such autogenerated code can become a starting point for implementing 5G Core.

## Discussion

### Could you give an overview of 5G Core NFs?

There are dozens of NFs (and their services) for which APIs have been defined. The figure highlights that Service-Based Architecture (SBA) and Service-Based Interfaces (SBIs) are defined only for the control plane. SBA is based on web technologies. Services communicate via HTTP/2 over TLS over TCP/IP, and exchange data in JSON format. 

Non-SBA interfaces use telecom-specific protocols: NAS-MM (on N1), NGAP over SCTP (on N2), GTP-U over UDP (on N3), PFCP over UDP (on N4), and so on. 

An NF Service Producer exposes its services that are then invoked by an authorized NF Service Consumer. Producers and consumers can communicate directly or indirectly via Service Communication Proxy (SCP). A consumer can discover a producer via local configuration, via NRF (direct communication) or via SCP (indirect communication). 

Each service is self-contained, reusable and independent of another service, even if they're part of the same NF. Services may share some context data. A system procedure is basically invoking a sequence of NF services. 


### Where can I obtain the 5G Core APIs?

A descriptive overview of NFs is in section 6 of **TS 23.501**. Section 7 lists the services of each NF. In Release 17 (Oct 2023), there are a total of 28 NFs containing 102 services.   These are listed in the figure.

Section 5 of **TS 23.502** details all operations of each service. An operation can take the form of request/response or subscribe/notify. The document also gives the known consumers of each operation. Section 4 describes system procedures that make use of these operations. 

Stage 3 specifications (including API definitions in YAML) of each NF is the **TS 29.5xx series** of documents. An easier way to obtain the API definitions is via the 5G APIs repository at 3GPP Forge. The README file in this repository includes links to view/edit/validate/test each API via Swagger Editor UI. 


### Which are the REST principles adopted by 5G SBA?

Code on Demand and HATEOAS are two REST principles currently not used in 5G SBA. Otherwise, the following have been adopted: 

    + **Resource, Serialization and Representation**: Resources/objects are accessed via unique URIs. They're serialized as JSON documents.
    + **Client/Server**: Clients are service consumers while servers are service producers. The same NF can take on different roles in different contexts. For example, when registering with NRF, SMF is the client and NRF is the server. When creating a session, SMF is the server and AMF is the client.
    + **Stateless**: Servers don't maintain any state about clients. Clients include all necessary information with each request. This allows for load balancing, scalability and resilience in a distributed environment. UDSF offers a centralized storage and thereby facilitates stateless implementations. If an NF instance goes down, another instance can obtain context data (such as Service Profile used at SMF) from UDSF. UDR and UDSF can't be stateless.
    + **Cacheable**: Servers indicate if clients can cache the information.
    + **Layered System**: Clients need not be aware exactly which server provides a service. NRF allows this decoupling of clients and servers.
    + **HTTP Methods**: GET, POST, PUT, PATCH and DELETE are used.

### What communication types does 5GC SBA adopt?

For CRUD operations, **Request/Response** communication is used. An NF consumer requests. An NF producer responds. POST method is used on a parent resource to create a new child resource. The latter's URI is returned in the response. Another way to create a resource is to use PUT method on the resource itself. In this case, the NF consumer selects the resource identifier and URI. Resource can be read with GET method accompanied with necessary query parameters. Resource updates can be done with PUT (full update) or PATCH (partial update). Resource deletion is via DELETE method. 

There's also **Subscribe/Notify** communication. An NF consumer subscribes by providing a callback URI and an optional filter. An NF producer notifies the consumer when data changes and matches the filter. Subscriptions are created with POST, updated with PUT or PATCH, and deleted with DELETE. Notifications use POST. Subscriptions can be of explicit or implicit. For example, UDR is implicitly subscribed to provisioned subscriber data at the UDR. Another example is an AMF instance that creates an SM Context for a PDU Session. That instance is implicitly subscribed to SM Context Status at the SMF. 


### What's the structure of URIs used by 5GC SBA?

The figure shows the structure and an example of the `nf-instances` resource from NRF NFManagement API. API Root, API Name and API Version are collectively called API URI. API URI doesn't include a trailing forward slash. Variable `nfInstanceID` is delimited with `{}`. In the example, this is replaced with UUID to indicate the specific instance. 

API Version follows semantic versioning of the form `vx.y.z` where `x`, `y` and `z` are positive integers. Only the major version (`x` part) is indicated in the URI. A suffix starting with hyphen indicates pre-release version (eg. `1.0.0-alpha1`). A suffix starting with plus sign indicates build metadata after release freeze (eg. `3.0.1+orange.2020-09`). An NF consumer can use NRF to discover supported versions of NF producer instances. 


### What are some challenges in implementing 5GC?

Multi-vendor deployments are complex with respect to interoperability, provisioning, dependencies, Operations Support Systems (OSSs), etc. AI-driven approaches may help avoid manual work. Engineers need to skill themselves in system integration. Operators remain undecided if they should get into system integration themselves or adopt a pre-packaged solution from a consortium. 

3GPP permits custom operations using POST method. It also permits custom RPC-style API operations. However, these will adversely impact interoperability.

A service mesh such as Istio isn't aligned with the 3GPP approach of using NRF for service discovery or UPF selection by SMF. However, 3GPP does suggest using a service mesh for SCP. 

OpenAPI is meant to simplifying implementation due to readily available validators, code generators and other tools. The open source OpenAPI Generator is able to generate code in many languages. When run against 5G specifications, it shows its limitations. As on December 2023, the project has close to 4,000 open issues. 

## Milestones

2000

Fielding describes **Representational State Transfer (REST)** in his PhD dissertation. He proposes REST as a guide to enhancing HTTP, not building web APIs per se. He notes that any architectural style (such as REST) is not a silver bullet to solve all types of problems. REST itself is meant for "large-grain hypermedia data transfer". 

Jun  
2018

3GPP publishes **TS 29.501, v15.0.0**, titled *Principles and Guidelines for Services Definition; Stage 3*. In v15.1.0 (September 2018), security requirements of API design and JSON structures in query parameters are specified. Subsequent versions include v16.0.0 (June 2019) and v17.0.0 (December 2020). 

Aug  
2020

5G Core APIs specified in YAML files are hosted at 3GPP Forge. While this is a GitLab environment, GitLab tools and processes can't fully be used. This is because changes can happen only via 3GPP mandated Change Requests (CRs). 

May  
2023

At a **multi-vendor trial**, Enea demonstrates fast network slicing. A network slice can be instantiated quickly. Software comes from Enea, Oracle and Casa Systems. Enea supplied UDM, UDR and AUSF. Hardware included those from HPE, Intel and Nokia. However, achieving this in a commercial network is not expected to be straightforward.