6 API Definitions

29.5573GPP5G SystemApplication Function ProSe ServiceRelease 18Stage 3TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

6.1 Naf_ProSe Service API

6.1.1 Introduction

The Naf_ProSe shall use the Naf_ProSe API.

The API URI of the Naf_ProSe 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 "naf-prose ".

– 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 naf-prose API is contained in Annex A.2.

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].

JSON Merge Patch, as defined in IETF RFC 7396 [17], signalled by the content type "application/merge-patch+json".

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

In this release of this specification, no resource is defined for the Naf_ProSe Service.

6.1.4 Custom Operations without associated resources

6.1.4.1 Overview

The structure of the custom operation URIs of the Naf_ProSe Service is shown in figure 6.1.4.1-1.

Figure 6.1.4.1-1: Resource URI structure of the Naf_ProSe API

Table 6.1.4.1-1 provides an overview of the custom operations and applicable HTTP methods.

Table 6.1.4.1-1: Custom operations

Custom operation URI	Mapped HTTP method	Description
/authorize-discovery	POST	Obtain the authorization of Discovery Request from the 5G DDNMF for a UE.
/authorization-update-result	POST	Inform the AF of the result of the revocation request to update authorization information

6.1.4.2 Operation: authorize-discovery

6.1.4.2.1 Description

This clause represents the custom operation and what it is used for, and the custom operation URI.

6.1.4.2.2 Operation Definition

This operation shall support request data structures specified in table 6.1.4.2.2-1 and response data structures specified in table 6.1.4.2.2-2.

Table 6.1.4.2.2-1: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
AuthDisReqData	M	1	Contains the request data to obtain the authorization for a UE of a 5G ProSe Discovery Request.

Table 6.1.4.2.2-2: Data structures supported by the POST Response Body on this resource

Data type	P	Cardinality	Response codes	Description
AuthDisResData	M	1	200 OK	Contains the response data for the authorization of a 5G ProSe Direct Discovery Request for a UE.
N/A			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative AF.
N/A			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative AF.
ProblemDetails	O	0..1	403 Forbidden	(NOTE 2)
NOTE 1: 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. NOTE 2: Failure cases are described in clause 6.1.7.3.

Table 6.1.4.2.2-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF.

Table 6.1.4.2.2-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF.

6.1.4.3 Operation: authorization-update-result

6.1.4.3.1 Description

This clause represents the custom operation and what it is used for, and the custom operation URI.

6.1.4.3.2 Operation Definition

This operation shall support request data structures specified in table 6.1.4.3.2-1 and response data structures specified in table 6.1.4.3.2-2.

Table 6.1.4.3.2-1: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
AuthUpdateData	M	1	Contains the result of the revocation request to update authorization information for Restricted ProSe Direct Discovery.

Table 6.1.4.3.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	This case represents successful report of discovery authorization update result.
N/A			307 Temporary Redirect		Temporary redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative AF.
N/A			308 Permanent Redirect		Permanent redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative AF.
ProblemDetails	O	0..1		403 Forbidden	(NOTE 2)
NOTE 1: 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. NOTE 2: Failure cases are described in clause 6.1.7.3.

Table 6.1.4.3.2-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF.

Table 6.1.4.3.2-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF.

6.1.5 Notifications

6.1.5.1 General

Table 6.1.5.1-1 provides an overview of the notification operation and applicable HTTP method.

Table 6.1.5.1-1: Notifications overview

Notification	Callback URI	HTTP method	Description
DiscoveryAuthorizationUpdateNotify	{authUpdateCallbackUri}	POST	Update the authorization information to revoke discovery permissions related to some other users in the NF service consumer (e.g. 5G DDNMF).

6.1.5.2 DiscoveryAuthorizationUpdateNotify

6.1.5.2.1 Description

The DiscoveryAuthorizationUpdateNotify service operation is used to update the authorization information to revoke discovery permissions related to some other users in the NF service consumer (e.g. 5G DDNMF).

6.1.5.2.2 Notification Definition

Call-back URI: {authUpdateCallbackUri}

See clause 5.2.2.2.1 for the description of how the AF obtains the Call-back URI of the NF service consumer.

6.1.5.2.3 Notification Standard Methods

6.1.5.2.3.1 POST

This method sends a discovery authorization update notification to the NF service consumer.

This method shall support the request and response data structures and response codes specified in table 6.1.5.2.3.1-1 and table 6.1.5.2.3.1-2.

Table 6.1.5.2.3.1-1: Data structures supported by the POST Request Body

Data type	P	Cardinality	Description
AuthUpdateData	M	1	Input parameters to the "DiscoveryAuthorizationUpdateNotify" service operation, including the updated authorization information for Restricted ProSe Direct Discovery.

Table 6.1.5.2.3.1-2: Data structures supported by the POST Response Body

Data type	P	Cardinality	Response codes	Description
n/a			204 No Content	This case represents successful notification of the event.
N/A			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative AF.
N/A			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative AF.
ProblemDetails	O	0..1	403 Forbidden	(NOTE 2)
NOTE 1: 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. NOTE 2: Failure cases are described in clause 6.1.7.3.

Table 6.1.5.2.3-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF.

Table 6.1.5.2.3-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF.

6.1.6 Data Model

6.1.6.1 General

This clause specifies the application data model supported by the Naf_ProSe API.

Table 6.1.6.1-1 specifies the data types defined for the Naf_ProSe service based interface.

Table 6.1.6.1-1: Naf_ProSe specific Data Types

Data type	Clause defined	Description	Applicability
AuthDisReqData	6.1.6.2.2	Represents Data used to request the authorization for a UE of 5G ProSe Direct Discovery Request.
AuthDisResData	6.1.6.2.3	Represents the obtained authorization Data for a UE of 5G ProSe Direct Discovery Request.
TargetData	6.1.6.2.4	Represents a combination of Target PDUID – Target RPAUID – Metadata Indicator.
AllowedSuffixNum	6.1.6.3.2	Represents the allowed number of suffixes.
AppLevelContainer	6.1.6.3.2	Represents an Application Layer Container.
MetadataIndic	6.1.6.3.5	Contains Metadata Indicator.
AuthRequestType	6.1.6.3.3	Represents the authorization request type.
AuthResponseType	6.1.6.3.4	Represents the authorization response type.
ProSeRestrictedMask	6.1.6.3.2	Represents a Prose Restricted Mask.
AuthUpdateData	6.1.6.2.5	Represents the updated authorization information for Restricted ProSe Direct Discovery.
BannedAuthData	6.1.6.2.6	Represents a set of Banned RPAUID – Banned PDUID that are no longer allowed to discover the ProSe Restricted Code corresponding to the user’s RPAUID for the Application ID associated with that AF.
RevocationResult	6.1.6.3.6	Represents the revocation result of a set of Banned RPAUID – Banned PDUID for Restricted ProSe Direct Discovery.

Table 6.1.6.1-2 specifies data types re-used by the Naf_ProSe service based interface from other specifications, including a reference to their respective specifications, and when needed, a short description of their use within the Naf_ProSe Service based interface.

Table 6.1.6.1-2: Naf_ProSe re-used Data Types

Data type	Reference	Comments	Applicability
ProseApplicationId	3GPP TS 29.555 [16]	A string representing the ProSe Application ID.
ProseApplicationCodeSuffixPool	3GPP TS 29.555 [16]	Contains a ProSe Application Code Suffix Pool.
Rpauid	3GPP TS 29.555 [16]	Represents a Restricted ProSe Application User ID.
Pduid	3GPP TS 29.555 [16]	Represents a ProSe Discovery UE ID.
ProseApplicationMask	3GPP TS 29.555 [16]	Represents a Mask for a ProSe Application Code Suffix corresponding to a ProSe Applicantation ID.
MetaData	3GPP TS 29.555 [16]	Contains Metadata.
RestrictedCodeSuffixPool	3GPP TS 29.555 [16]	Contains a ProSe Restricted Code Suffix pool.
Uri	3GPP TS 29.571 [18]	Contains a URI.

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: AuthDisReqData

Table 6.1.6.2.2-1: Definition of type AuthDisReqData

Attribute name	Data type	P	Cardinality	Description	Applicability
authRequestType	AuthRequestType	M	1	This attribute contains the authorization request type for 5G ProSe Direct Discovery.
proseAppId	array(ProseApplicationId)	O	0..N	This attribute contains the ProSe Application ID(s). (NOTE)
allowedSuffixNum	AllowedSuffixNum	O	0..1	This attribute contains the allowed number of suffixes.
appLevelContainer	AppLevelContainer	O	0..1	This attribute contains an application level container.
rpauid	Rpauid	O	0..1	This attribute contains the RPAUID.
targetRpauid	Rpauid	O	0..1	This attribute contains the Target RPAUID.
authUpdateCallbackUri	Uri	O	0..1	The call-back URI of the NF service consumer (i.e. 5G DDNMF) for implicit subscription to notification of DiscoveryAuthorizationUpdateNotify.
NOTE: If provided, at least one element shall be present in the attribute “proseAppId”.

6.1.6.2.3 Type: AuthDisResData

Table 6.1.6.2.3-1: Definition of type AuthDisResData

Attribute name	Data type	P	Cardinality	Description	Applicability
authResponseType	AuthResponseType	M	1	This attribute contains the authorization response type for 5G ProSe Direct Discovery.
proseAppCodeSuffixPool	ProseApplicationCodeSuffixPool	O	0..1	This attribute contains the ProSe Application Code Suffix Pool.
pduids	array(Pduid)	O	0..N	This attribute contains the PDUID(s) corresponding to the provided RPAUID.
restrictedCodeSuffixPool	array(RestrictedCodeSuffixPool)	O	0..N	This attribute contains a ProSe Restricted Code Suffix pool. (NOTE)
proseAppMasks	array(ProseApplicationMask)	O	0..N	This attribute contains the mask(s) for the ProSe Application Code Suffix(es) corresponding to the ProSe Application ID.
proSeRestrictedMasks	array(ProSeRestrictedMask)	O	0..N	This attribute contains the mask(s) for the ProSe Restricted Code Suffix(es) corresponding to each of the Target RPAUID(s).
resAppLevelContainer	AppLevelContainer	O	0..1	This attribute contains the Application Level Container.
targetDataSet	array(TargetData)	O	0..N	This attribute contains N sets of Target PDUID – Target RPAUID – Metadata Indicator.
targetPduid	Pduid	O	0..1	This attribute contains the Target PDUID.
metaData	MetaData	O	0..1	This attribute contains metadata corresponding to the Target PDUID.
NOTE: If provided, exactly one element shall be present in the attribute.

6.1.6.2.4 Type: TargetData

Table 6.1.6.2.4-1: Definition of type TargetData

Attribute name	Data type	P	Cardinality	Description	Applicability
targetRpauid	Rpauid	M	1	This attribute contains the RPAUID.
pduid	Pduid	M	1	This attribute contains the Target PDUID.
metadataIndic	MetadataIndic	O	0..1	This attribute is optional and contains the Metadata Indicator to indicate whether there is metadata associated with the RPAUID, and if so, whether updates of metadata is allowed. (NOTE)
NOTE: The default value of metadataIndic is "NO_METADATA" if this attribute is not supplied.

6.1.6.2.5 Type: AuthUpdateData

Table 6.1.6.2.5-1: Definition of type AuthUpdateData

Attribute name	Data type	P	Cardinality	Description	Applicability
targetRpauid	Rpauid	M	1	This attribute contains the RPAUID of the user that would like to revoke discovery permissions of some other users in the AF.
bannedAuthData	array(BannedAuthData)	M	1..N	The attribute contains N sets of Banned RPAUID – Banned PDUID that are no longer allowed to discover the ProSe Restricted Code corresponding to the user’s RPAUID for the Application ID associated with that AF.

6.1.6.2.6 Type: BannedAuthData

Table 6.1.6.2.6-1: Definition of type BannedAuthData

Attribute name	Data type	P	Cardinality	Description	Applicability
bannedRpauid	Rpauid	M	1	The attribute contains a RPAUID within a Banned RPAUID – Banned PDUID set that is no longer allowed to discover the ProSe Restricted Code corresponding to the user’s RPAUID for the Application ID associated with the AF.
bannedPduid	Pduid	M	1	The attribute contains the PDUID within a Banned RPAUID – Banned PDUID set that is no longer allowed to discover the ProSe Restricted Code corresponding to the user’s RPAUID for the Application ID associated with the AF.
revocationResult	RevocationResult	C	0..1	The attribute contains the revocation result of a set of Banned RPAUID – Banned PDUID for Restricted ProSe Direct Discovery, which is only conveyed in within a DiscoveryAuthorizationResultUpdate service operation

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
AllowedSuffixNum	integer	Contains the allowed number of suffixes.
AppLevelContainer	sting	Contains the Application Level Container.
ProSeRestrictedMask	string	Contains a ProSe Restricted Mask.

6.1.6.3.3 Enumeration: AuthRequestType

The enumeration AuthRequestType represents the Authorization Request Type. It shall comply with the provisions of table 6.1.6.3.3-1.

Table 6.1.6.3.3-1: Enumeration AuthRequestType

Enumeration value	Description	Applicability
OPEN_DISCOVERY_EXTENSION_ANNOUNCE	Indicates that the Authorization Request Type is "open discovery with application-controlled extension/announce".
RESTRICTED_DISCOVERY_ANNOUNCE	Indicates that the Authorization Request Type is "restricted discovery/announce".
RESTRICTED_DISCOVERY_EXTENSION_ANNOUNCE	Indicates that the Authorization Request Type is "restricted discovery with application-controlled extension/announce".
OPEN_DISCOVERY_EXTENSION_MONITOR	Indicates that the Authorization Request Type is "open discovery with application-controlled extension/monitor".
RESTRICTED_DISCOVERY_MONITOR	Indicates that the Authorization Request Type is "restricted discovery/monitor".
RESTRICTED_DISCOVERY_EXTENSION_MONITOR	Indicates that the Authorization Request Type is "restricted discovery with application-controlled extension/monitor".
RESTRICTED_DISCOVERY_PERMISSION	Indicates that the Authorization Request Type is "restricted discovery/permission".
RESTRICTED_DISCOVERY_RESPONSE	Indicates that the Authorization Request Type is "restricted discovery/response".
RESTRICTED_DISCOVERY_QUERY	Indicates that the Authorization Response Type is "restricted discovery/query".
RESTRICTED_DISCOVERY_MATCH	Indicates that the Authorization Response Type is "restricted discovery/match".

6.1.6.3.4 Enumeration: AuthResponseType

The enumeration AuthRequestType represents the Authorization Response Type. It shall comply with the provisions defined in table 6.1.6.3.4-1.

Table 6.1.6.3.4-1: Enumeration AuthResponseType

Enumeration value	Description	Applicability
OPEN_DISCOVERY_EXTENSION_ANNOUNCE_ACK	Indicates that the Authorization Response Type is "open discovery with application-controlled extension/announce ack".
RESTRICTED_DISCOVERY_ANNOUNCE_ACK	Indicates that the Authorization Response Type is "restricted discovery/announce ack".
RESTRICTED_DISCOVERY_EXTENSION_ANNOUNCE_ACK	Indicates that the Authorization Response Type is "restricted discovery with application-controlled extension/announce ack".
OPEN_DISCOVERY_EXTENSION_MONITOR_ACK	Indicates that the Authorization Response Type is "open discovery with application-controlled extension/monitor ack".
RESTRICTED_DISCOVERY_MONITOR_ACK	Indicates that the Authorization Response Type is "restricted discovery/monitor ack".
RESTRICTED_DISCOVERY_EXTENSION_MONITOR_ACK	Indicates that the Authorization Response Type is "restricted discovery with application-controlled extension/monito ack".
RESTRICTED_DISCOVERY_PERMISSION_ACK	Indicates that the Authorization Response Type is "restricted discovery /permission ack".
RESTRICTED_DISCOVERY_RESPONSE_ACK	Indicates that the Authorization Response Type is "restricted discovery /response ack".
RESTRICTED_DISCOVERY_QUERY_ACK	Indicates that the Authorization Response Type is "restricted discovery /query ack".
RESTRICTED_DISCOVERY_MATCH_ACK	Indicates that the Authorization Response Type is "restricted discovery /match ack".

6.1.6.3.5 Enumeration: MetadataIndic

The enumeration MetadataIndic represents the possible options for metadata associated with a particular target RPAUID. It shall comply with the provisions of table 6.1.6.3.5-1.

Table 6.1.6.3.5-1: Enumeration MetadataIndic

Enumeration value	Description	Applicability
NO_METADATA	Indicates that there is no metadata associated with the target RPAUID.
METADATA_UPDATE_DISALLOWED	Indicates that there is metadata associated with the target RPAUID, but it is not allowed to update this metadata.
METADATA_UPDATE_ALLOWED	Indicates that there is metadata associated with the target RPAUID, and it is allowed to update this metadata.

6.1.6.3.6 Enumeration: RevocationResult

The enumeration RevocationResult represents the revocation result of a set of Banned RPAUID – Banned PDUID for Restricted ProSe Direct Discovery. It shall comply with the provisions of table 6.1.6.3.6-1.

Table 6.1.6.3.6-1: Enumeration MetadataIndic

Enumeration value	Description	Applicability
REVOCATION_SUCCESSFUL	Indicates the successful revocation for a set of Banned RPAUID – Banned PDUID for Restricted ProSe Direct Discovery.
REVOCATION_NOT_SUCCESSFUL	Indicates that unsuccessful revocation for a set of Banned RPAUID – Banned PDUID for Restricted ProSe Direct Discovery.

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 Naf_ProSe 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 Naf_ProSe 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 Naf_ProSe service are listed in table 6.1.7.3-1.

Table 6.1.7.3-1: Application errors

Application Error	HTTP status code	Description
UNSPECIFIED	403 Forbidden	The request is rejected due to unspecified reasons.

6.1.8 Feature negotiation

The optional features in table 6.1.8-1 are defined for the Naf_ProSe 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 Naf_ProSe 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 Naf_ProSe 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 Naf_ProSe service.

The Naf_ProSe API defines a single scope "naf_prose" for OAuth2 authorization (as specified in 3GPP TS 33.501 [8]) for the entire service, and it does not define any additional scopes at resource or operation level.

Annex A (normative):
OpenAPI specification