6 API Definitions
29.5533GPP5G ProSe Anchor Services5G SystemRelease 18Stage 3TS
6.1 Npanf_ProseKey Service API
6.1.1 Introduction
The Npanf_ProseKey service shall use the Npanf_ProseKey API.
The API URI of the Npanf_ProseKey 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 "npanf-prosekey".
– 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 Npanf_ProseKey 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 Npanf_ProseKey API.
Figure 6.1.3.1-1: Resource URI structure of the Npanf_ProseKey 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 name |
Resource URI |
HTTP method or custom operation |
Description |
|
Prose Keys |
/prose-keys/register |
register (POST) |
Store the Prose Context |
|
/prose-keys/retrieve |
retrieve (POST) |
Retrieve the CP-PRUK |
6.1.3.2 Resource: Prose Keys
6.1.3.2.1 Description
This resource is used to represent Prose Keys Registration and Retrieval.
6.1.3.2.2 Resource Definition
Resource URI: {apiRoot}/npanf-prosekey/<apiVersion>/prose-keys
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 |
6.1.3.2.3 Resource Standard Methods
No HTTP method has been defined for the Prose Keys resource.
6.1.3.2.4 Resource Custom Operations
6.1.3.2.4.1 Overview
Table 6.1.3.2.4.1-1: Custom operations
|
Operation name |
Custom operation URI |
Mapped HTTP method |
Description |
|
register |
/prose-keys/register |
POST |
Store the Prose Context Info |
|
retrieve |
/prose-keys/retrieve |
POST |
Retrieve the CP-PRUK |
6.1.3.2.4.2 Operation: register
6.1.3.2.4.2.1 Description
The registration custom operation is used by the NF service consumer (AUSF) to store the Prose context info. For details see 3GPP TS 33.503 [14].
6.1.3.2.4.2.2 Operation Definition
This operation shall support the request data structures specified in table 6.1.3.2.4.2.2-1 and the response data structure and response codes specified in table 6.1.3.2.4.2.2-2.
Table 6.1.3.2.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
ProseContextInfo |
M |
1 |
Contains the SUPI, CP-PRUK, CP-PRUK ID, RSC. |
Table 6.1.3.2.4.2.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
Upon success, an empty response body shall be returned. |
||
|
ProblemDetails |
O |
0..1 |
404 Not Found |
The "cause" attribute may be used to indicate one of the following application errors: – USER_NOT_FOUND |
|
NOTE: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
6.1.3.2.4.3 Operation: retrieve
6.1.3.2.4.3.1 Description
The retrieval custom operation is used by the NF service consumer (AUSF) to retrieve the Prose Key. For details see 3GPP TS 33.503 [14].
6.1.3.2.4.3.2 Operation Definition
This operation shall support the request data structures specified in table 6.1.3.2.4.3.2-1 and the response data structure and response codes specified in table 6.1.3.2.4.3.2-2.
Table 6.1.3.2.4.3.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
ProseKeyRequest |
M |
1 |
Contains the 5GPRUK ID, RSC. |
Table 6.1.3.2.4.3.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
ProseKeyResponse |
M |
1 |
200 OK |
Upon success, a response body containing the Prose Key shall be returned. |
|
ProblemDetails |
O |
0..1 |
404 Not Found |
The "cause" attribute may be used to indicate one of the following application errors: – USER_NOT_FOUND – DATA_NOT_FOUND |
|
NOTE: The mandatory HTTP error status code for the POST 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
There is no custom operation without associated resources supported in Npanf_ProseKey Service.
6.1.5 Notifications
There is no notification defined for Npanf_ProseKey service.
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 Npanf_ProseKey service based interface protocol.
Table 6.1.6.1-1: Npanf_ProseKey specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
ProseContextInfo |
6.1.6.2.2 |
ProSe Context Information |
|
|
ProseKeyRequest |
6.1.6.2.3 |
Contains the CP-PRUK ID, RSC. |
|
|
ProseKeyResponse |
6.1.6.2.4 |
Contains the CP-PRUK |
|
|
5GPruk |
6.1.6.3.2 |
ProSe Remote User Key over Control Plane |
Table 6.1.6.1-2 specifies data types re-used by the Npanf_ProseKey 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 Npanf_ProseKey service based interface.
Table 6.1.6.1-2: Npanf_ProseKey re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
RelayServiceCode |
3GPP TS 29.571 [15] |
Relay Service Code |
|
|
Supi |
3GPP TS 29.571 [15] |
see 3GPP TS 23.501 [2] clause 5.9.2 |
|
|
5GPrukId |
3GPP TS 29.571 [15] |
ProSe Remote User Key ID over Control Plane |
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: ProseContextInfo
Table 6.1.6.2.2-1: Definition of type ProseContextInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
supi |
Supi |
M |
1 |
The SUPI of the UE |
|
|
5gPrukId |
5GPrukId |
M |
1 |
This IE shall indicate the CP-PRUK ID of the 5G ProSe Remote UE. |
|
|
5gPruk |
5GPruk |
M |
1 |
This IE shall indicate the CP-PRUK of the 5G ProSe Remote UE. |
|
|
relayServiceCode |
RelayServiceCode |
M |
1 |
This IE shall indicate the Relay Service Code from the 5G ProSe Remote UE. |
6.1.6.2.3 Type: ProseKeyRequest
Table 6.1.6.2.3-1: Definition of type ProseKeyRequest
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
5gPrukId |
5GPrukId |
M |
1 |
This IE shall indicate the CP-PRUK ID of the 5G ProSe Remote UE. |
|
|
relayServiceCode |
RelayServiceCode |
M |
1 |
This IE shall indicate the Relay Service Code from the 5G ProSe Remote UE. |
6.1.6.2.4 Type: ProseKeyResponse
Table 6.1.6.2.4-1: Definition of type ProseKeyResponse
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|||||
|
5gPruk |
5GPruk |
M |
1 |
This IE shall indicate the CP-PRUK of the 5G ProSe Remote UE. |
||||||
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 |
|
5GPruk |
string |
ProSe Remote User Key over Control Plane String value carrying the CP-PRUK in hexadecimal presentation. pattern: "^[A-Fa-f0-9]{64}$" |
6.1.6.4 Data types describing alternative data types or combinations of data types
There is no data type describing alternative data types or combinations of data types in Npanf_ProseKey Service.
6.1.6.5 Binary data
There is no binary data type in Npanf_ProseKey Service.
6.1.7 Error Handling
6.1.7.1 General
For the Npanf_ProseKey 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 Npanf_ProseKey API.
6.1.7.2 Protocol Errors
No specific procedures for the Npanf_ProseKey service are specified.
6.1.7.3 Application Errors
The application errors defined for the Npanf_ProseKey service are listed in Table 6.1.7.3-1.
Table 6.1.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
|
USER_NOT_FOUND |
404 Not Found |
The provided subscriber identifier is not found. |
|
DATA_NOT_FOUND |
404 Not Found |
The requested data is not found/does not exist. |
6.1.8 Feature negotiation
The optional features in table 6.1.8-1 are defined for the Npanf_ProseKey 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 Npanf_ProseKey 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 Npanf_ProseKey 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 Npanf_ProseKey service.
The Npanf_ProseKey API defines a single scope "npanf-prosekey" for the entire service, and it does not define any additional scopes at resource or operation level.
Annex A (normative):
OpenAPI specification