6 API Definitions
29.5783GPP5G SystemMobile Number Portability ServicesRelease 18Stage 3TS
6.1 Nmnpf_NPStatus Service API
6.1.1 Introduction
The Nmnpf_NPStatus service shall use the Nmnpf_NPStatus API.
The API URI of the Nmnpf_NPStatus API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URIs used in HTTP requests from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>
with the following components:
– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].
– The <apiName> shall be "nmnpf-npstatus".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 6.1.3.
6.1.2 Usage of HTTP
6.1.2.1 General
HTTP/2, IETF RFC 7540 [11], shall be used as specified in clause 5 of 3GPP TS 29.500 [4].
HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].
The OpenAPI [6] specification of HTTP messages and content bodies for the Nmnpf_NPStatus API is contained in Annex A.
6.1.2.2 HTTP standard headers
6.1.2.2.1 General
See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.
6.1.2.2.2 Content type
JSON, IETF RFC 8259 [12], shall be used as content type of the HTTP bodies specified in the present specification as specified in clause 5.4 of 3GPP TS 29.500 [4]. The use of the JSON format shall be signalled by the content type "application/json".
"Problem Details" JSON object shall be used to indicate additional details of the error in a HTTP response body and shall be signalled by the content type "application/problem+json", as defined in IETF RFC 7807 [13].
6.1.2.3 HTTP custom headers
The mandatory HTTP custom header fields specified in clause 5.2.3.2 of 3GPP TS 29.500 [4] shall be supported, and the optional HTTP custom header fields specified in clause 5.2.3.3 of 3GPP TS 29.500 [4] may be supported.
6.1.3 Resources
6.1.3.1 Overview
This clause describes the structure for the Resource URIs and the resources and methods used for the service.
Figure 6.1.3.1-1 depicts the resource URIs structure for the Nmnpf_NPStatus API.
Figure 6.1.3.1-1: Resource URI structure of the Nmnpf_NPStatus API
Table 6.1.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 6.1.3.1-1: Resources and methods overview
|
Resource purpose/name |
Resource URI (relative path after API URI) |
HTTP method or custom operation |
Description (service operation) |
|
NPstatus |
/{gpsi} |
GET |
Retrieve the NP status of the GPSI |
6.1.3.2 Resource: NPstatus
6.1.3.2.1 Description
This resource represents the Number Portability status for a GPSI.
6.1.3.2.2 Resource Definition
Resource URI: {apiRoot}/nmnpf-npstatus/<apiVersion>/{gpsi}
This resource shall support the resource URI variables defined in table 6.1.3.2.2-1.
Table 6.1.3.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 6.1.1 |
|
gpsi |
Gpsi |
See 3GPP TS 29.571 [15]; the only valid format is MSISDN |
6.1.3.2.3 Resource Standard Methods
6.1.3.2.3.1 GET
This method shall support the URI query parameters specified in table 6.1.3.2.3.1-1.
Table 6.1.3.2.3.1-1: URI query parameters supported by the GET method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
n/a |
This method shall support the request data structures specified in table 6.1.3.2.3.1-2 and the response data structures and response codes specified in table 6.1.3.2.3.1-3.
Table 6.1.3.2.3.1-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 6.1.3.2.3.1-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
NpStatusInfo |
M |
1 |
200 OK |
Upon success, the response body contains the Number Portability Status information. |
|
ProblemDetails |
O |
0..1 |
404 Not Found |
The "cause" attribute may be used to indicate one of the following application errors: – GPSI_NOT_FOUND |
|
NOTE: The mandatory HTTP error status code for the GET method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
6.1.4 Custom Operations without associated resources
None.
6.1.5 Notifications
None.
6.1.6 Data Model
6.1.6.1 General
This clause specifies the application data model supported by the API.
Table 6.1.6.1-1 specifies the data types defined for the Nmnpf_NPStatus service based interface protocol.
Table 6.1.6.1-1: Nmnpf_NPStatus specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
NpStatusInfo |
6.1.6.2.2 |
Number Portability Status Information |
Table 6.1.6.1-2 specifies data types re-used by the Nmnpf_NPStatus service based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nmnpf_NPStatus service based interface.
Table 6.1.6.1-2: Nmnpf_NPStatus re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
Gpsi |
3GPP TS 29.571 [15] |
General Public Subscription Identifier |
|
|
ProblemDetails |
3GPP TS 29.571 [15] |
Error description |
|
|
PlmnId |
3GPP TS 29.571 [15] |
PLMN Identity |
6.1.6.2 Structured data types
6.1.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
6.1.6.2.2 Type: NpStatusInfo
Table 6.1.6.2.2-1: Definition of type NpStatusInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
subscriptionNetwork |
PlmnId |
M |
1 |
Identifies the GPSI’s subscriptionNetwork |
|
|
tbc |
6.1.6.3 Simple data types and enumerations
6.1.6.3.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
6.1.6.3.2 Simple data types
The simple data types defined in table 6.1.6.3.2-1 shall be supported.
Table 6.1.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
6.1.6.4 Data types describing alternative data types or combinations of data types
None.
6.1.6.5 Binary data
None.
6.1.7 Error Handling
6.1.7.1 General
For the Nmnpf_NPStatus API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [5]. Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [4] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.2.7.1-1 of 3GPP TS 29.500 [4].
In addition, the requirements in the following clauses are applicable for the Nmnpf_NPStatus API.
6.1.7.2 Protocol Errors
Protocol errors handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [4].
6.1.7.3 Application Errors
The application errors defined for the Nmnpf_NPStatus service are listed in Table 6.1.7.3-1.
Table 6.1.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
6.1.8 Feature negotiation
The optional features in table 6.1.8-1 are defined for the Nmnpf_NPStatus API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].
Table 6.1.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
6.1.9 Security
As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nmnpf_NPStatus API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [9]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [10]) plays the role of the authorization server.
If OAuth2 is used, an NF Service Consumer, prior to consuming services offered by the Nmnpf_NPStatus API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [10], clause 5.4.2.2.
NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Nmnpf_NPStatus service.
The Nmnpf_NPStatus API defines a single scope "nmnpf-npstatus" for the entire service, and it does not define any additional scopes at resource or operation level.
Annex A (normative):
OpenAPI specification