4 Design Principles for 5GC SBI APIs
29.5013GPP5G SystemPrinciples and Guidelines for Services DefinitionRelease 18Stage 3TS
4.1 General Principles
Each 5GC SBI API specification should include the following information for each specified service:
– Purpose of the API;
– URIs of resources;
– Supported HTTP methods for a given resource;
– Supported representations (e.g. JSON, see IETF RFC 8259 [3]);
– Request body schema(s) (where applicable);
– Response body schema(s) (where applicable);
– Supported response status codes;
– Relation types supported if HATEOAS is implemented by the API;
– A reference in the resource description clause to one of the archetypes defined in Annex C if the resource design matches one of them; and
– A list defining identifiers of optional features (see clause 6.6 of 3GPP TS 29.500 [2] for related procedures).
For each specified service a clause to a normative Annex should be provided containing the OpenAPI definitions according to OpenAPI Specification [4] for the service. The specifications should state that content of this normative annex takes precedence when being discrepant to other parts of the specification with respect to the encoding of information elements and methods.
NOTE: The semantics and procedures, as well as conditions, e.g. for the applicability and allowed combinations of attributes or values, not expressed in the OpenAPI definitions but defined in other parts of the specification also apply.
The TS Skeleton Template as provided in Annex A should be used as a starting point when drafting 5GC SBI API specifications.
Common procedures, HTTP extensions and error handling applicable to several 5GC SBI API specifications should be defined in 3GPP TS 29.500 [2] and should be referenced from individual 5GC SBI API specifications.
Common data types applicable to several 5GC SBI API specifications should be defined in 3GPP TS 29.571 [5] and should be referenced from individual 5GC SBI API specifications.
4.2 API Design Style and REST Implementation Levels
4.2.1 General
5GC SBI API specifications should apply a protocol design framework as follows:
a) REST-style service operations should implement the Level 2 of the Richardson maturity model, with standard HTTP methods, whenever it is a good match for the style of interaction to model, e.g. service operations that can naturally map to one of the standard methods (CRUD operations), this should be the preferred modelling attempt;
b) service operations may use custom API operations (RPC-style interaction), when it is seen a better fit for the style of interaction to model, e.g. non-CRUD service operations;
c) it is possible to mix REST-style operations and RPC-style operations in the same API.
NOTE: Level 3 (HATEOAS) of the Richardson maturity model in the 5G Service-Based Architecture can be implemented by an API but is optional. Hypermedia usage guidelines are provided in clause 4.7 of the present specification.
4.2.2 API Design Principles for Query Operation
When designing a query operation API, i.e. the NF service consumer invokes the API aiming to retrieve certain information from the NF service producer, the following principles should be applied:
a) if the query operation does not require any input parameter for the NF service producer, then the REST-style service operation with standard HTTP GET method should be used (see clause 4.6.1.1.2);
b) if
– the query operation requires input parameter(s) for the NF service producer; and
– all the required input parameter(s) are used to identify a particular resource and/or control the content of the result of the query operation;
then the REST-style service operation with standard HTTP GET method should be used (see clause 4.6.1.1.2);
c) standard HTTP GET method shall not be used for non-safe operations and non-idempotent operations.
4.2.3 API Design Principles for Delete Operation
When designing a delete operation API, i.e. the NF service consumer invokes the API aiming to delete certain resource on the NF service producer, the following principles should be applied:
a) if the delete operation does not require any input parameter for the NF service producer, then the REST-style service operation with standard HTTP DELETE method should be used (see clause 4.6.1.1.4);
b) if
– the delete operation requires input parameter(s) for the NF service producer; and
– all the required input parameter(s) are used to identify a particular resource and/or control the content of the result of the delete operation;
then the REST-style service operation with standard HTTP DELETE method should be used (see clause 4.6.1.1.4);
c) standard HTTP DELETE method shall not be used for non-idempotent operations.
4.3 Version Control
4.3.0 General
The version control mechanism in the present clause allows the management of changes to an API and provides a version number that is incremented whenever changes to the API are applied.
NOTE: The version number does not reflect the usage of optional features. A mechanism to negotiate the usage of optional features is defined in clause 6.6 of 3GPP TS 29.500 [2].
4.3.1 Structure of API version numbers
4.3.1.1 API version number format
API version numbers shall consist of at least 3 fields, following a MAJOR.MINOR.PATCH pattern according to the Semantic Versioning Specification [17].
The 1st field (MAJOR), the 2nd field (MINOR), and the 3rd field (PATCH) shall contain unsigned integer numbers, and they shall not contain leading zeroes.
An additional field (called "pre-release version" in Semantic Versioning Specification [17]) is added to denote an OpenAPI version under development, i.e. prior to the freeze of the corresponding OpenAPI description for a given 3GPP Release. This additional field is appended after the 3 first version fields using the hyphen "-" character and shall have the format "alpha.n", where "n" is an unsigned integer number without leading zeroes.
After the freeze of a 3GPP Release, additional fields (called "build metadata" in Semantic Versioning Specification [17]), containing operator-specific version information, may be appended after the 3 first version fields using the plus sign "+" character and they shall consist of a list of dot-separated identifiers, where each identifier may contain only alphanumeric characters and hyphens ([0-9A-Za-z-]).
NOTE: Operator-specific version information are ignored when determining version precedence. Thus, two versions that differ only in the operator-specific version information, have the same precedence.
EXAMPLES:
"1.0.0-alpha.1"
"3.0.1+orange.2020-09"
4.3.1.2 Rules for incrementing field values
The first version of a new API under development shall obtain the version number "1.0.0-alpha.1". At the first publication of the 3GPP Technical Specification defining the API after the OpenAPI freeze of the first 3GPP Release that contains the API, the version number of the API shall be set to "1.0.0".
When a new version of the 3GPP TS containing OpenAPI file(s) is published, the fields of the corresponding API version number(s) shall be incremented according to the following rules:
1st Field (MAJOR):
– This numerical field shall be incremented when:
a) there are one or more backward incompatible changes to the API after the OpenAPI freeze for a given 3GPP Release; and
b) there are the first backward incompatible change(s) to the existing API with respect to the latest version in the previous 3GPP Release while a 3GPP Release is under development (i.e. prior to the OpenAPI freeze for a given 3GPP Release).
EXAMPLE 1: Assuming that 3GPP Rel-16 under development contains API version "1.1.0-alpha.2", and a backward incompatible change with respect to the latest version in the previous 3GPP Release is applied to that API before the OpenAPI freeze, the new Rel-16 API version is "2.0.0-alpha.1".
NOTE 1: Subsequent changes in a given 3GPP Release under development do not lead to increment of the 1st field (MAJOR) and 2nd field (MINOR).
NOTE 2: Rules for determining backward incompatible changes are provided in Annex B.
NOTE 3: It is recommended to avoid backward incompatible change to the API after the OpenAPI freeze whenever possible, especially after OpenAPI freeze of a succeeding Release. It is preferable to introduce such changes only in the 3GPP Release under development.
– If a backward incompatible change needs to be applied to several 3GPP Releases the following applies:
a) If the 3GPP Releases contain different MAJOR versions of the same API, a new MAJOR API version shall be assigned to each 3GPP Release in the order of those 3GPP Releases in such a manner that the lowest of those 3GPP Releases shall obtain the first unassigned MAJOR version value.
EXAMPLE 2: Assuming that 3GPP Rel-15 contains API version "1.0.0", and Rel-16 contains API version "2.0.0", and that the same backward incompatible change is applied to that API in both Releases, the new Rel-15 API version is "3.0.0" and the new Rel-16 API version is "4.0.0".
b) If the 3GPP Releases contain the same MAJOR version but different MINOR versions of the same API, a single new MAJOR API version value shall be assigned for all those 3GPP Releases, unless other backward incompatible changes only applied to some of those Releases require the creation of separate MAJOR versions.
NOTE 4: For each such Release a new MINOR version is assigned.
EXAMPLE 3: Assuming that 3GPP Rel-15 and Rel-16 contain API version "1.0.0", and Rel-17 contains API version "1.2.0", and that the same backward incompatible change is applied to that API in all 3GPP Releases, the new 3GPP Rel-15 and Rel-16 API version is "2.0.0" and the new 3GPP Rel-17 API version is "2.2.0".
c) If the 3GPP Releases contain the same API versions, a single new API version shall be assigned for all those 3GPP Releases, unless other changes only applied to some of those Releases require the creation of separate versions.
EXAMPLE 4: Assuming that 3GPP Rel-15 and 3GPP Rel-16 contain API version "1.0.0", and that only the same backward incompatible change is applied to that API in both 3GPP Releases, the new 3GPP Rel-15 and Rel-16 API version is "2.0.0".
EXAMPLE 5: Assuming that 3GPP Rel-15 and Rel-16 contain API version "1.0.0", and that the same backward incompatible change is applied to that API in both Releases and an additional backward compatible change is applied in 3GPP Rel-16, the new 3GPP Rel-15 API version is "2.0.0", and the 3GPP Rel-16 API version is "2.1.0".
EXAMPLE 6: Assuming that 3GPP Rel-15 and Rel-16 contain API version "1.0.0", and that the same backward incompatible change is applied to that API in both Releases and an additional backward incompatible change is applied in 3GPP Rel-16, the new 3GPP Rel-15 API version is "2.0.0", and the 3GPP Rel-16 API version is "3.0.0".
2nd Field (MINOR):
– This numerical field shall be incremented when:
a) there are the first one or more backward compatible changes not corresponding to changes to earlier 3GPP Releases (i.e. changes introduced by 3GPP CR with other categories than "mirror") to the same API in a given 3GPP Release without any prior backward incompatible changes in that Release. If the same 1st field (MAJOR) and the 2nd field (MINOR) are assigned to n previous 3GPP Releases, a MINOR version number shall be reserved for each intermediate 3GPP Release for possible subsequent changes in that Release and the MINOR version number shall be incremented by n; and
EXAMPLE 7: Assuming that 3GPP Rel-15 and Rel-16 contain API version "1.0.0" (because there were no changes to the API in Rel-16), and in Rel-17 the first backward compatible new feature is added before the OpenAPI freeze, the API version "1.2.0-alpha.1" is assigned to Rel-17.
b) there are one or more subsequent backward compatible additions of features not corresponding to changes to previous 3GPP Releases to the API in a frozen 3GPP Release before a higher MINOR number has been allocated for the same MAJOR version (for a subsequent Release).
– This field shall be reset to "0" if the 1st field (MAJOR) is changed, unless a backward incompatible change needs to be applied to several 3GPP Releases that already contain the same MAJOR but different MINOR API versions. In that case a single new major API version is assigned, and for each such 3GPP Release with an own MINOR version, a new MINOR version shall be assigned, starting with MINOR version "0" for the lowest such Release, and reserving a MINOR version number for each intermediate Release without an own MINOR version. (see Example 3)
NOTE 5: In most cases the MINOR version is incremented when new backward compatible features are added in a 3GPP Release. In rare cases, where only backward compatible changes not corresponding to changes to previous 3GPP Releases are applied to a 3GPP Release, the MINOR version is also incremented. It is recommended to avoid such changes in 3GPP Releases without added functionality whenever possible.
NOTE 6: Subsequent backward compatible changes in a given 3GPP Release before OpenAPI freeze do not lead to an increment of the 2nd field (MINOR).
NOTE 7: Changes corresponding to changes in previous 3GPP Releases do not lead to an increment of the 2nd field (MINOR).
NOTE 8: If two 3GPP Releases are under parallel development (because the work on Rel-X+1 has commenced before the OpenAPI freeze of Rel-X), the corresponding APIs will obtain distinct values of the 1st field (MAJOR) or 2nd field (MINOR).
EXAMPLE 8: Assuming that an API was introduced with version "1.0.0" in Rel-15, and that the Rel-16 version is "1.1.0-alpha.5" because the OpenAPI is not yet frozen in Rel-16, and that a new backward compatible Rel-17 feature is added, the Rel-17 API version is "1.2.0-alpha.1".
3rd Field (PATCH):
– This numerical field shall be incremented:
a) if the changes are only one or more backward-compatible corrections (but no changes requiring an update of the 1st field (MAJOR) or of the 2nd field (MINOR) are made to the API after the OpenAPI freeze of a 3GPP Release; and
b) if one or more backward compatible additions of features, but no changes requiring an update of the 1st field (MAJOR) or of the 2nd field (MINOR), are made to the API after the OpenAPI freeze of a 3GPP Release and after the assignment of a MINOR version to a higher 3GPP Release.
– This field shall be reset to "0" if the 1st field (MAJOR) or 2nd field (MINOR) is changed.
NOTE 9: Before the OpenAPI freeze for a given 3GPP Release, the 3rd field will not be incremented.
NOTE 10: If the 1st field (MAJOR) and 2nd field (MINOR) were not incremented between 3GPP Releases (because there were no added features and no backward incompatible changes), and the same backward compatible changes are then applied to those 3GPP Releases, the API files in those 3GPP Releases are identical and will obtain the same API version number.
NOTE 11: In rare cases for which a new backward compatible functionality needs to be added in an older 3GPP Release after the OpenAPI freeze and work on that API already started in a later Release, the new functionality is exceptionally introduced as a PATCH correction and a new supported feature could be defined accordingly.
Possible additional fields:
– Pre-Release version field
– Before the OpenAPI freeze of a 3GPP Release, an additional field (separated from the 3 first version fields by a hyphen "-" character) shall be supplied as follows:
a) When the 1st or 2nd field is incremented before the OpenAPI freeze of a 3GPP Release, this field shall obtain the value "alpha.1".
b) The numerical value "n" within the field value "alpha.n" shall be incremented if one or more subsequent changes are made to the API under development.
– After the OpenAPI freeze of a 3GPP Release, this additional field (including the hyphen "-" character) containing pre-release version info is removed from the API version.
– Operator-specific version field(s)
– After the OpenAPI freeze of a 3GPP Release, additional fields may be supplied based on operator policy after the 3 first version fields and separated by a plus sign "+" character. The rules for setting, or incrementing, such fields are out of the scope of 3GPP, but they shall comply with the rules described in the Semantic Versioning Specification [17], and contain a list of dot-separated labels within the allowed character set ([0-9A-Za-z-]).
If no change is applied to an API in a new published TS version, the API version number shall not be incremented unless the additional field ("-alpha.n") needs to be removed at OpenAPI freeze. This also applies if the TS is published in a new 3GPP Release.
NOTE 12: OpenAPI files can contain references to other OpenAPI files. Changes to referenced parts of such other OpenAPI files need to be considered when determining if and how to update an API version.
NOTE 13: The API version number of those version fields managed by 3GPP is incremented using 3GPP change requests.
4.3.1.3 Visibility of the API version number fields
The API version shall be indicated in the resource URI of every API, as described in clause 4.4.1.
The API version shall be indicated as the concatenation of the letter "v" and the 1st field of the API version number.
The other fields shall not be included in the resource URI.
NOTE: Including these digits in the URI would force the NF service consumer to select a specific sub-version, at the risk of seeing the request rejected if the NF service provider does not support it, while the request could have been served by ignoring unknown elements.
The full API version number (i.e., containing all the fields) shall be visible in the OpenAPI specifications, in the "version" subfield of the "info" field, as described in clause 5.3.3.
4.3.1.4 Relation to the Technical Specification version number
There is no one-to-one mapping between an API version number and the version number of the 3GPP Technical Specification defining this API.
A 3GPP Technical Specification specifies one or more APIs, which may have different versions.
A change in the 3rd field of a 3GPP TS version number (i.e. an editorial change) should not lead to a change in the version number of the APIs specified in the 3GPP TS.
A change in the 1st and 2nd fields of the 3GPP TS version number is likely to lead to at least a change in the minor version number of the APIs specified in the 3GPP TS.
EXAMPLE: If version 15.4.1 of a 3GPP TS contains version "1.1.1" of API A, B and C, and a version 16.0.0 of this 3GPP TS is derived from version 15.4.1, TS version 16.0.0 can contain version "1.2.0.alpha-1" of API A (if all changes made are backward compatible), version "2.0.0.alpha-1" of API B (if some changes are no backward compatible) and version "1.1.1" of API C (if no changes were made).
The 3GPP TS defining the API is indicated in the OpenAPI specification of the API, as described in clause 5.3.4.
4.3.1.5 Discovery of the supported versions
The NF service consumer may discover the API version(s) supported by an NF service producer using the following mechanisms:
– NRF query: The NF service consumer may retrieve from the NRF the NF profile of a given NF Instance. This NF profile contains the full version number(s) of the API(s) supported by an NF Service Instance, as described in the clause 6.2.6.2.4 of 3GPP TS 29.510 [18] and the planned retirement date.
– NF profile change notifications: The NF service consumer may subscribe for NF status change notifications with the NRF as specified in clause 5.2.2.5 of 3GPP TS 29.510 [18]. The NRF shall notify as specified in clause 5.2.2.6 of 3GPP TS 29.510 [18], any change to the NF profile which may include updated NF service profile containing the current list of NF services and their versions supported by the NF.
When a new major version is created, the NF service producer shall continue supporting at least the previous major version until a retirement date unless all API versions (except for draft API versions published prior to the OpenAPI freeze) with that previous major version are withdrawn (see clause 4.3.1.6); this enables NF service consumers to migrate to the new version. After expiration of the retirement date, the old major version should be deprecated. The retirement date of an old major version supported by a NF service instance may be updated in the NF profile in the NRF.
4.3.1.6 Withdrawing API versions
If it is discovered that one or several previous API versions are not providing the basic mandatory functionality of an API due to severe functional or encoding deficits (for instance, there is no or very limited interoperability between the NF service consumer and NF service producer when such an API version is used, or the API is hardly implementable because of severe deficits in the OpenAPI file that cannot easily be fixed by implementers in an interoperable manner), those API versions shall be listed as withdrawn in subsequent versions of the TS defining the corresponding API; any withdrawn API versions from the same or previous 3GPP releases shall be listed. API versions published before the OpenAPI freeze of the corresponding 3GPP Release, i.e. with a 4th Field (DRAFT) as part of the version number, shall not be withdrawn.
NOTE 1: It is recommended to avoid withdrawing API versions whenever possible. It is expected that a need to withdraw API versions is most likely detected when discussing corrections soon after the OpenAPI freeze of a new API.
NOTE 2: Corrections to optional or minor parts of the API functionality do not lead to the withdrawal of API versions. However, if severe functional or encoding deficits of the functionality related to an optional functionality with a corresponding supported feature (see 3GPP TS 29.500 [2] clause 6.6.2) are discovered, a new supported feature can be introduced to enable a negotiation of the support of the correction, and the old corresponding supported feature can be marked as "withdrawn" in the table defining the supported features of an API.
Withdrawn API versions should not be deployed.
4.4 URI Structure
4.4.1 Resource URI structure
Resources are either individual resources, or structured resources that can contain child resources. It is recommended to design each resource following one of the archetypes provided in the Annex C.
A URI uniquely identifies a resource. In the 5GC SBI APIs, when a resource URI is an absolute URI, its structure shall be specified as follows:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>
"apiRoot" shall be a concatenation of the following parts:
– scheme ("http" or "https")
NOTE: In this release of the specification both http and https scheme URIs are allowed. See clause 13.1 of 3GPP TS 33.501[22] for further details on security of Service Based Interfaces.
– the fixed string "://"
– authority (host and optional port) as defined in IETF RFC 3986 [9]. The host should be represented by the operator specific FQDN (for FQDN examples see clause 28.3.2 in 3GPP TS 23.003 [27]).
– an optional deployment-specific string (API prefix) that starts with a "/" character.
apiName" shall define the name of the API. For example, ‘nsmf-pdusession’.
"apiVersion" shall indicate the MAJOR version of the API. The format is specified in clause 4.3.1.3. For example, ‘v1’.
While "apiRoot", "apiName" and "apiVersion" together define the API URI of the corresponding API, each "apiSpecificResourceUriPart" defines a resource URI of the API relative to the API URI.
An API URI should not contain a trailing slash as defined in clause 3.1, and if it contains one, then it should be ignored/removed.
Example of an API URI from 3GPP TS 29.502 [20]:
– url: ‘{apiRoot}/nsmf-pdusession/v1’
4.4.2 Custom operations URI structure
The custom operation definition is in Annex C.
The URI of a custom operation which is associated with a resource shall have the following structure:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>/<custOpName>
Custom operations can also be associated with the service instead of a resource. The URI of a custom operation which is not associated with a resource shall have the following structure:
{apiRoot}/<apiName>/<apiVersion>/<custOpName>
In the above URI structures, "apiRoot", "apiName", "apiVersion" and "apiSpecificResourceUriPart" are as defined in clause 4.4.1 and "custOpName" represents the name of the custom operation as defined in clause 5.1.3.2.
4.4.3 Callback URI structure
The purpose of the callback URI is to enable NF service consumer to provide the URI to be used by an NF Service Producer to send notification or callback requests.
The callback URI shall be in the form of an absolute URI as defined in clause 4.3 of IETF RFC 3986 [9], including an authority, and excluding any query component, any fragment component and any userinfo subcomponent.
Therefore, callback URI consists of the following components, specified with ABNF syntax (see IETF RFC 5234 [26]):
URI = scheme ":" "//" host [ ":" port ] / path
Where ‘host’ is either an FQDN or an IP address and the ‘path’ is a path to an NF consumer resource.
4.5 Resource Representation and Content Format Negotiation
4.5.1 Resource Representation
A resource representation is a serialization of the resource state in a particular content format. It’s included in the data frame of an HTTP/2 request or response. Representation header fields provide metadata about the representation. When a message includes a data frame, the representation data enclosed in the data frame. HTTP/2 reuses the definition of Representation header as HTTP 1.1 in IETF RFC 7231 [6]. Content-type field in HTTP/2 header performs as representation header fields and describes the representation data that would have been enclosed in the data frame, e.g. if content-type is application/json, resource representation in data frame is serialized in JSON format.
Server supports the content format of the representation received in the data frame of the request and returns the "200 OK" response code.
4.5.2 Content Format Negotiation
IETF RFC 7231 [6] provides a mechanism to negotiate the content format of a representation.
In HTTP/2 requests and responses, the "Content-Type" HTTP/2 header field is used to signal the format of the actual representation included in the data frame. If the format of the representation in an HTTP/2 request is not supported by the server, it responds with the "415 Unsupported Media Type" response code.
For GET method, the "Accept" HTTP header of the HTTP/2 request signals the content formats that a client supports. If the server cannot provide any of the accepted formats, it returns the "406 Not Acceptable" response code.
4.6 Use of HTTP Methods
4.6.1 Use of Request/Response Communication
4.6.1.1 CRUD
4.6.1.1.1 Creating a Resource
4.6.1.1.1.1 General
Procedures that allow an NF service consumer to create a new resource at the NF service producer shall be specified to either use the HTTP POST method with procedures according to clause 4.6.1.1.1.2 or the HTTP PUT method with procedures according to clause 4.6.1.1.1.3.
4.6.1.1.1.2 Creating a Resource using POST
The HTTP POST method (see IETF RFC 7231 [6]) allows an NF service consumer to create a new child resource at the NF service producer in such a manner that the NF service producer selects the child resource identifier and the URI for the child resource.
Figure 4.6.1.1.1.2-1 illustrates creating a resource using POST.
Figure 4.6.1.1.1.2-1: Creating a resource using POST
1. The parent resource of which the new resource is to be created as a child is identified by the request URI. The payload body of the POST request shall contain a representation of the resource to be created without a child resource identifier. For forward compatibility, the NF service producer ignores unknown attributes in the received resource representation unless specified otherwise by the particular application.
2. The NF service producer generates a child resource identifier and constructs the URI for the created resource by appending that child resource identifier to the parent resource URI received as request URI of the POST request (e.g. "…/parent-resource/childresource1").
On success, "201 Created" shall be returned, the payload body of the POST response should contain a representation of the created resource, and the "Location" header shall be present and shall contain the URI of the created resource. The created resource shall be served by the same NF (service) instance that received the service request, unless the 5GC SBI API specifications explicitly specified that in specific use cases the created resource may be served by another NF (service) instance. If in such specific use cases the resource is created in a different NF (service) instance, the identifier of the serving NF (service) instance shall be included in the response message.
If the HTTP scheme used in the returned URI is "https", then the authority of the URI included in the Location header shall be an FQDN, and not an IP address.
The URI included in the "Location" header may be an absolute URI or a relative URI reference (see IETF RFC 3986 [9]); when the URI is in relative form, the base URI used to resolve the URI reference is the target URI included in the received POST request.
NOTE: The representations of the resource in the request and response can differ, e.g. the representation of the resource in the response can be empty or can contain a subset of the representation as received in the request possibly with modified attributes, and in addition can contain additional attributes. Exact details will be specified by the application.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the POST response body (see clause 4.8).
A collection may be used to model a resource that serves as a directory of resources that may be distributed on different processing instances or hosts. If so:
– the authority and/or deployment-specific string of the apiRoot of the created resource URI returned by the NF Service Producer in the "Location" header may differ from the authority and/or deployment-specific string of the apiRoot of the request URI received in the POST request.
– the NF Service Consumer shall be capable to receive and process an authority and/or deployment-specific string in the apiRoot of the created resource URI that differs from the authority and/or deployment-specific string of the apiRoot of the Request URI.
It needs to be clearly stated in the 5GC SBI API specifications when a NF Service Producer may return a different authority and/or deployment-specific string in the apiRoot of the created resource URI for a collection resource.
4.6.1.1.1.3 Creating a Resource using PUT
The HTTP PUT method (see IETF RFC 7231 [6]) allows an NF service consumer to create a new resource at the NF service producer in such a manner that the NF service consumer selects the resource identifier and the URI for the resource.
Figure 4.6.1.1.1.3-1 illustrates creating a resource using HTTP PUT.
Figure 4.6.1.1.1.3-1: Creating a Resource using HTTP PUT
1. The NF service consumer selects a resource identifier and constructs the URI for the resource to be created by appending that resource identifier to the parent resource URI. The resource that is to be created is identified by that URI as request URI. The payload body of the PUT request shall contain a representation of the resource to be created. For forward compatibility, the NF service producer ignores unknown attributes in the received resource representation unless specified otherwise by the particular application.
2. On success, "201 Created" shall be returned, the payload body of the PUT response should contain the representation of the created resource, and the "Location" header shall be present and shall contain the URI of the created resource. The created resource shall be served by the same NF (service) instance that received the service request, unless the 5GC SBI API specifications explicitly specified that in specific use cases the created resource may be served by another NF (service) instance. If in such specific use cases the resource is created in a different NF (service) instance, the identifier of the serving NF (service) instance shall be included in the response message.
If the HTTP scheme used in the returned URI is "https", then the authority of the URI included in the Location header shall be an FQDN, and not an IP address.
NOTE: The representations of the resource in the request and response can differ, e.g. the representation of the resource in the response can be empty or can contain a subset of the representation as received in the request possibly with modified attributes, and in addition can contain additional attributes. Exact details will be specified by the application.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).
If the resource that is to be created already exists at the NF service producer, the following applies:
1) If the update of that resource by PUT is supported, the existing representation of the resource is replaced with the representation received in the PUT request body; see clause 4.6.1.1.3.1.
2) If the update of that resource by PUT is not supported, the "403 Forbidden" HTTP status code shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).
4.6.1.1.2 Reading a Resource
4.6.1.1.2.1 Reading a Single Resource
Procedures that allow a service consumer NF (client) to read information from the server shall be specified to use the HTTP GET method (see IETF RFC 7231 [6]) to obtain the current representation of a resource.
Figure 4.6.1.1.2-1 illustrates reading a resource.
Figure 4.6.1.1.2.1-1: Reading a resource
1. The resource of which a representation is to be obtained is identified by the request URI. Query parameters may be used to control the content of the result.
The payload body of the GET request shall be empty.
2. On success, "200 OK" shall be returned and the payload body of the GET response shall contain the obtained resource representation.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the GET response body (see clause 4.8).
4.6.1.1.2.2 Querying a Set of Resources
Procedures that allow a service consumer NF (client) to querying a set of resources from the server shall be specified to use HTTP GET method towards a resource modelled as Collection or Store archetype.
Query parameters (see clause 4.6.1.1.5) may be provided when querying a set of resources. The query component contains non-hierarchical data that, along with data in the path component, to filter the resources identified within the scope of the URI’s scheme to a subset of the resources matching the query parameters. The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") character or by the end of the URI.
Figure 4.6.1.1.2.2-1: Query of a collection of resources by using query parameters.
Step 1. The client shall send a HTTP GET request using the URI of a resource modelled as Collection or Store archetype, optionally with query parameters, to the server.
Step 2. On success, the server shall return a set of sub-resources that includes only those entries filtered by the query parameters. If no sub-resource is matched for the querying service operation, the server shall return "200 OK" with an empty array (e.g. "[ ]" in JSON) in response body. If the resource in the URI doesn’t exist on the server, the server shall return "404 Not Found" with optionally the cause information in response body.
NOTE: The result array/empty array can be defined as an attribute of an object, if the service operation returns an object in the response payload for extensibility consideration.
Clause 4.9 specifies some possible options for an NF Service Producer to return the representations of multiple resources to a NF Service Consumer.
4.6.1.1.3 Updating a Resource
4.6.1.1.3.1 Usage of HTTP PUT
Procedures that allow a service consumer NF (client) to update information stored at the server by means of a complete replacement shall be specified to use the HTTP PUT method to replace the current representation of a resource with a new representation.
Figure 4.6.1.1.3.1-1 illustrates updating a resource using HTTP PUT.
Figure 4.6.1.1.3.1-1: Updating a Resource using HTTP PUT
1. The resource that is to be updated is identified by the request URI. The payload body of the PUT request shall contain the new representation of the resource. For forward compatibility, the NF service producer ignores unknown attributes in the received resource representation unless specified otherwise by the particular application.
2. On success, "204 No Content" or "200 OK" shall be returned.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).
If the resource that is to be updated does not exist at the NF service producer, the following applies:
1. If the creation of that resource by PUT is supported, the resource is created according to the procedure in clause 4.6.1.1.1.3.
2. If the creation of that resource by PUT is not supported, the "403 Forbidden" HTTP status code shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).
4.6.1.1.3.2 Usage of HTTP PATCH
Procedures that allow a service consumer NF (client) to update information stored at the server by means of a partial replacement shall be specified to use the HTTP PATCH method (see IETF RFC 5789 [10]) to modify the current representation of a resource according to given modification instructions. The format of the PATCH message body shall be specified for each resource where the PATCH method is supported using one or several of the following encodings:
– If no modification of individual elements within an array needs to be supported, the "JSON Merge Patch" encoding of changes defined in IETF RFC 7396 [7] should be used.
– If a modification of individual elements within an array needs to be supported, the "JSON Patch" encoding of changes defined in IETF RFC 6902 [8] shall be used.
A single of the above encodings shall be specified for each resource where the PATCH method is supported unless backward compatibility considerations necessitate the support of both encodings.
NOTE 1: In Rel-15 a single encoding will be selected for each resource as backward compatibility considerations do not yet apply.
NOTE 2: "JSON Merge Patch" does not support the modification of individual elements within an array. However, it supports the modification of individual elements within maps (see clause 5.2.4.2). Collections of elements can be modelled as maps, instead of arrays, if a partial modification using PATCH is desired.
NOTE 3: The Open API description of the body of HTTP PATCH requests is specified in clause 5.3.8.
Figure 4.6.1.1.3.2-1 illustrates updating a resource using HTTP PATCH.
Figure 4.6.1.1.3.2-1: Updating a Resource using HTTP PATCH
1. The resource that is to be updated is identified by the request URI. The payload body of the PATCH request shall contain a description of the requested modifications of the resource. For the "JSON Merge Patch" encoding defined in IETF RFC 7396 [7] and the "Content-Type" header shall be set to "application/merge-patch+json". For the "JSON Patch" encoding of changes defined in IETF RFC 6902 [8] the "Content-Type" header shall be set to "application/json-patch+json". For forward compatibility, the NF service producer shall ignore received modification instructions of unknown attributes in the resource unless specified otherwise by the particular application.
2. On success, "204 No Content" or "200 OK" shall be returned.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PATCH response body (see clause 4.8).
4.6.1.1.4 Deleting a Resource
Procedures that allow a service consumer NF (client) to delete a resource from the server shall be specified to use the HTTP DELETE method (see IETF RFC 7231 [6]).
Figure 4.6.1.1.4-1 illustrates deleting a resource.
Figure 4.6.1.1.4-1: Deleting a resource
The resource that is to be deleted is identified by the request URI.
The payload body of the DELETE request shall be empty.
On success, "204 No Content" should be returned and then the payload body of the DELETE response shall be empty.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the DELETE response body (see clause 4.8).
4.6.1.1.5 Query Parameters
4.6.1.1.5.1 General
The query component in the URI contains non-hierarchical data that, along with data in the path component, to filter the resources identified within the scope of the URI’s scheme to a subset of the resources matching the query parameters. The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") character or by the end of the URI. The syntax of the query component is specified in IETF RFC 3986 [9].
When a server receives a request with a query component, it shall parse the query string in order to identify filters. The first question mark is used to be a separator and is not part of the query string. A query string is composed of a series of "key=value" pairs, separated by "&". If one query parameter contains more than one value, i.e. an array of data elements, different values shall be separated by comma (",").
The behaviour of the server, when receiving an HTTP/2 method with a query parameter which is of type array and only some of the members in the array can be matched, depends on each API and the behaviour shall be clearly described.
If multiple query parameters are defined for a method on the resource, the logical ‘AND’ represents the default logical relationship between the query parameters for this resource. If a logical relationship between multiple query parameters is specified in an API, then this overrides the default relationship. If multiple query parameters are defined for a method on the resource in an API, but there is no need to specify any logical relationship between these query parameters, the API shall explicitly state this.
4.6.1.1.5.2 Complex query expression
The complex query expression is used when there are multiple query parameters in the URI and the query condition needs to be expressed by a logical combination of multiple query parameters which overrides the default logical relationship of the query parameters. The complex query expression is either a Conjunctive Normal Form (CNF) or a Disjunctive Normal Form (DNF) which is equivalent to the logical combination of query parameters reflecting the query condition.
The "complex-query" query parameter may be used when a complex query expression is needed to express a query condition. The value of the "complex-query" query parameter is of type "ComplexQuery" which is a JSON object, the corresponding CNF or DNF is encoded into that JSON object (see 3GPP TS 29.571 [5] for the details of the data type "ComplexQuery"). The use of "complex-query" shall be negotiated using the feature negotiation procedure as defined in 3GPP TS 29.500 [2].
If a query parameter is included in the "complexQuery" then the same query parameter shall not be included outside the "complexQuery" in the same request message.
NOTE 1: It is not assumed that all APIs support "complex-query", the API supports this feature only when it is described in the corresponding specification.
NOTE 2: The logical relationship between "complex-query" and the other query parameters defined for a particular API is described in the corresponding specification of that API.
NTOE 3: The "complex-query" is not an additional explanation of the other query parameters, the condition expressed in the "complex-query" is evaluated along with the other queries.
4.6.1.2 Custom Operations
Custom Operations provide procedures that allow a service consumer NF (client) to interact with an NF service producer in other ways than what is supported by the CRUD methods described in clause 4.6.1.1.
Custom Operation can be related to a resource or can be related to an entire service and be independent of a resource.
Figure 4.6.1.2-1 illustrates the use of a custom operation related to a resource.
Figure 4.6.1.2-1: Custom Operation on a Resource using HTTP POST
1. The request URI identifies the custom operation to be executed and the resource the custom operation relates to and is constructed by adding a verb as name for the custom operation at the end of the resource URI (see clauses 4.4.2 and 5.1.3.2). Parameters for the custom operation are included in the request body.
2. On success, "204 No Content" or "200 OK" shall be returned. "200 OK" shall contain a body with data related to the custom operation.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the POST response body (see clause 4.8).
Figure 4.6.1.2-2 illustrates the use of a custom operation related to a service.
Figure 4.6.1.2-2: Custom Operation related to Service using HTTP POST
1. The request URI identifies the custom operation to be executed and is constructed by adding a verb as name for the custom operation at the end of the service URI (see clauses 4.4.2 and 5.1.3.2). Parameters for the custom operation are included in the request body.
2. On success, "204 No Content" or "200 OK" shall be returned. "200 OK" shall contain a body with data related to the custom operation.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the POST response body (see clause 4.8).
4.6.1.3 Use of Asynchronous Operations
Certain service operations may be designed to allow the invocation of a request so that the response can be received asynchronously: if the NF service consumer when sending a request cannot expect to receive an immediate final response, the service consumer may provide a callback reference for final result notification. The service provider, when receiving a request that contains a callback reference for final result notification, may then return an immediate "202 Accepted", and notify the service consumer about the final result using the received callback reference at a later point in time.
4.6.1.4 Special provisions to support the seamless change of AMF as NF service producer
Services provided by the AMF can be transferred seamlessly to a new AMF when the corresponding UE context is transferred to that AMF.
To support a seamless change of the AMF as NF service producer, the procedures in clause 4.6.1 are applied with the following special provisions:
1. When becoming aware that a new AMF is serving the resource, the NF service consumer shall exchange the authority part of resource URIs with the address of a new NF service producer and shall use that URI in subsequent communication.
NOTE: An NF service consumer can become aware of an AMF change via Namf_Communication service AMFStatusChange Notifications, via Error response from old AMF, via link level failures (e.g. no response from the AMF), or via a notification from the NRF that the AMF has deregistered and can then determine the new AMF either via information received within those services or by selecting an AMF from an earlier received AMF set or the backup AMF.
2. Each AMF within a set of AMFs supporting seamless changes shall be prepared to receive updates for resource URIs constructed according to bullet 1 with the own IP address as authority part from the NF service consumer, by either handling the updates, or by replying with an HTTP "307 temporary redirect" error response pointing to new NF service producer, or by replying with another HTTP error such as an "404 Not found".
3. For a service that includes notifications from the AMF, the NF service consumer shall be prepared to receive notifications for the that service from any NF service producer within a set of NF service producers supporting seamless changes.
4.6.2 Use of Subscribe/Notify Communication
4.6.2.1 General
Subscribe/Notify communication between 5GC NFs can be used to keep involved NFs (consumers of a service) informed of data changes or events that occur at another NF (producer of the service). A notification is a message that contains information about the event.
Service consumer NFs (clients) need to subscribe to notifications at the service provider NF (server). This either happens explicitly by means of creating a new subscription resource (see clause 4.6.2.2), or implicitly by updating a relevant resource.
Service consumer NFs can in principle explicitly or implicitly subscribe to be notified about data change to any type of resource of any resource archetype (Document, Store or Collection). It is up to the API to define the resources that support subscriptions.
When the change/event occurs at the service producer NF, notifications (see clause 4.6.2.3) are sent from the service producer NF to the service consumer NFs. This communication initiated by the service producer to the service consumers requires that the service consumer NF (client) takes the role of an HTTP server and the service producer NF (server) takes the role of an HTTP client.
During the explicit subscription the service consumer NF (client) provides a callback URI and possibly additional filter criteria to the service producer NF (server). When the data-change/event occurs that matches the filter criteria in the subscription, the service producer NF (taking the role of an HTTP client) uses the provided callback URI to notify the service consumer NF (taking the role of an HTTP server) about the change.
4.6.2.2 Management of Subscriptions
4.6.2.2.1 General
The HTTP method to create a subscription shall be POST. The HTTP method to modify a subscription shall be PUT or PATCH. The HTTP method to delete a subscription (i.e. to unsubscribe) shall be DELETE (see IETF RFC 7231 [6]).
Subscriptions may be implicit, i.e. exist without being explicitly created by a dedicated subscribe operation.
Two types of implicit subscriptions exist:
1. The subscription is implied by an explicit operation different from the subscribe operation, which does not use the GET method. The subscription implied by the explicit operation and the corresponding notification shall be part of the same service.
2. The subscription exists without any explicit operation.
As an example for the first type, at the UDM the registered AMF (as long as it is registered) is implicitly subscribed to notification about de-registration and (possibly) P-CSCF restoration as side effect of the registration.
As another example for the first type, at the SMF, the AMF that created a SM Context for a PDU session is implicitly subscribed for SM Context Status notification. At AMF change the new AMF updates the SMF with its callback URI for receiving subsequent SM Context Status notification.
As an example for the second type, at the UDR any available UDM is implicitly subscribed to notification about changes of provisioned subscriber data. When provisioned subscriber data are modified at the UDR by means of provisioning, the UDR selects one of the available UDMs (i.e. one of the implicitly subscribed UDMs) and notifies it about the subscriber data change.
In the OpenAPI specification file, notifications for the second type of implicit subscriptions shall be specified as part of an explicit subscription.
4.6.2.2.2 Creation of a Subscription
Figure 4.6.2.2.2-1 illustrates explicit creation of a subscription.
Figure 4.6.2.2.2-1: Creation of a subscription
The parent resource (collection of subscriptions) is identified by the request URI.
The data structure in the payload body of the POST request shall contain a callback URI, and may contain additional criteria to filter the set of events that trigger a notification. The request may contain an expiry time, suggested by the NF Service Consumer as a hint, representing the time up to which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications.
On success, "201 Created" shall be returned, the payload body of the POST response shall contain a representation of the created subscription, and the "Location" header shall contain the URI of the created resource. The created resource shall be served by the same NF (service) instance that received the service request, unless the 5GC SBI API specifications explicitly specified that in specific use cases the created resource may be served by another NF (service) instance. If in such specific use cases the resource is created in a different NF (service) instance, the identifier of the serving NF (service) instance shall be included in the response message.
If the HTTP scheme used in the returned URI is "https", then the authority of the URI included in the Location header shall be an FQDN, and not an IP address.
The response based on operator policies and taking into account the expiry time included in the request, may contain an expiry time (i.e. a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. If an expiry time was included in the request, then the expiry time returned in the response should be less than or equal to that value. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time. If the expiry time is not included in the response, the NF Service Consumer shall consider the subscription to be valid without an expiry time.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the POST response body (see clause 4.9).
4.6.2.2.3 Modify a subscription
4.6.2.2.3.1 Modification of a Subscription Using HTTP PUT
Procedures that allow a NF service consumer to update the subscription at the server by means of a complete replacement shall use the HTTP PUT method to replace the current subscription with a new representation.
Figure 4.6.2.2.3.1-1 illustrates modification a subscription using HTTP PUT.
Figure 4.6.2.2.3.1-1: Modification a subscription using HTTP PUT
1. The NF Service Consumer shall send a PUT request to the resource URI representing the individual subscription. The payload body of the PUT request shall contain the subscription information to be replaced including the criteria to filter the set of events that trigger a notification. The request may contain an updated expiry time, suggested by the NF Service Consumer as a hint, to extend the subscription lifetime, representing the time upto which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications. If the request does not contain an expiry time, the NF Service Producer shall consider that the NF Service Consumer requests for an extension of the existing subscription lifetime without indicating any specific expiration time; still, the NF Service Producer shall be authoritative to set the expiry time in the subscription response according to its own policies.
2. On success, "204 No Content" without any response body or "200 OK" with a response body providing current resource representation shall be returned.
When "200 OK" is returned, the response based on operator policies and taking into account the expiry time included in the request, may contain an expiry time (i.e a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. If an expiry time was included in the request, then the expiry time returned in the response should be less than or equal to that value. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer, as specified in clause 4.6.2.2.2. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time. If the expiry time is not included in the response, the NF Service Consumer shall consider the subscription to be valid without an expiry time.
When "204 No Content" is returned, it shall be interpreted that the NF Service Producer accepted entirely the resource representation provided by the NF Service Consumer in the request; e.g., if the request contained a proposed expiry time, a 204 response shall be interpreted as if such timestamp is accepted by the NF Service Producer as the expiration time for the subscription and, similarly, if the request did not contain a proposed expiry time, a 204 response shall be interpreted as if no expiration time is set by the NF Service Producer for the subscription.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).
If the NF Service Consumer is not allowed to update the subscription information, the "403 Forbidden" HTTP status code shall be returned and appropriate additional error information should be returned in the PUT response body (see clause 4.8).
If the resource that is to be updated does not exist at the NF service producer, the "404 Not Found" HTTP status code shall be returned.
4.6.2.2.3.2 Modification of a Subscription Using HTTP PATCH
Procedures that allow a NF service consumer to update subscription at the server by means of a partial replacement shall use the HTTP PATCH method (see IETF RFC 5789 [10]) to modify the current subscription according to given modification instructions.
Figure 4.6.2.2.3.2-1 illustrates updating a resource using HTTP PATCH.
Figure 4.6.2.2.3.2-1: Modification a subscription using HTTP PATCH
1. The NF Service Consumer shall send a PATCH request to the resource URI representing the individual subscription. The payload body of the PATCH request shall contain the modification instructions. The request may contain an expiry time (i.e. a future timestamp), requested by the NF Service Consumer, representing the time upto which the subscription is desired to be kept active and the time after which the subscribed event shall stop generating notifications.
2. On success, "204 No Content" without any response body or "200 OK" with a response body containing the modified subscription information shall be returned. When "204 No Content" is returned and if the request included an expiry time, then the requested expiry time shall be accepted by the NF Service Producer. When "200 OK" is returned and if the request included an expiry time then the response based on operator policies and taking into account the expiry time included in the request, shall contain an expiry time (i.e. a future timestamp), as determined by the NF Service Producer, after which the subscription becomes invalid. If an expiry time was included in the request, then the expiry time returned in the response should be less than or equal to that value. Once the subscription expires, if the NF Service Consumer wants to keep receiving notifications, it shall create a new subscription in the NF Service Producer, as specified in clause 4.6.2.2.2. The NF Service Producer shall not provide the same expiry time (i.e. a future timestamp) for many subscriptions in order to avoid all of them expiring and recreating the subscription at the same time.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the PATCH response body (see clause 4.8).
4.6.2.2.4 Delete a subscription
Figure 4.6.2.2.4-1 illustrates explicit deletion of a subscription.
Figure 4.6.2.2.4-1: Deletion of a subscription
1. The NF Service Consumer shall send a DELETE request to the resource URI representing the individual subscription. The request body shall be empty.
2. On success, "204 No Content" shall be returned. The response body shall be empty.
On failure, the appropriate HTTP status code indicating the error shall be returned in the DELETE response body (see clause 4.8).
4.6.2.3 Notifications
The HTTP method for the notification that corresponds to an explicit subscription shall be POST (see IETF RFC 7231 [6]).
NOTE: Clause 5.3.7 describes how to encode Notifications in OpenAPI specification files.
Figure 4.6.2.3-1 illustrates a notification.
Figure 4.6.2.3-1: Notification
1. The callback reference provided during creation of the subscription resource, or otherwise known from implicit subscription, is used as the request URI. The callback reference for implicit subscriptions are obtained from the NRF. When an NF / NF service registers with the NRF, the default notification subscriptions along with the callback URI for receiving those notifications may be provided (see clause 6.1.6.2.3 of 3GPP TS 29.510 [18]).
The payload body of the POST request shall contain the notification payload.
The payload body of the notification should follow the resource definition of the subscribed resource and can for example be based on the resource definition of the GET operation, but it is up to the API to define the notification resource definition.
Each API that supports subscription to collection/store archetype resources, should specify in their semantics whether notifications should be sent by changes on the collection/store resource ONLY (i.e. creation/deletion of the main top-level resource itself, and creation/deletion of its children), or if in addition the consumer can expect to get notifications from changes on the resource representation.
2. On success, "200 OK" shall be returned if any information needs to be included in the payload body of the POST response; otherwise, "204 No Content" shall be returned and the payload body of the POST response shall be empty.
On failure, the appropriate HTTP status code indicating the error shall be returned and appropriate additional error information should be returned in the POST response body (see clause 4.8).
4.6.2.4 Special provisions to support the seamless change of AMF as NF service consumer
Services consumed by an AMF can be transferred seamlessly to a new AMF when the corresponding UE context is transferred to that AMF.
To support a seamless change of AMF as NF service consumer, the procedures in clause 4.6.2 are applied with the following special provisions:
1. When becoming aware that a new AMF is requiring notifications related to a subscription resource, the NF service producer shall exchange the authority part of the corresponding Notification URI with the address of that new NF service consumer and shall use that URI in subsequent communication.
NOTE: An NF service producer can become aware of an AMF change via Namf_Communication service AMFStatusChange Notifications, via Error response from old AMF, via link level failures (e.g. no response from the AMF), or via a notification from the NRF that the AMF has deregistered and can then determine the new AMF either via information received within those services or selecting an AMF from an earlier received AMF set or the backup AMF.
2. Each AMF within a set of AMFs supporting seamless changes shall be prepared to receive notifications at the Notification URI constructed according to bullet 1 with the own IP address as authority part from the NF service producer, by either handling the notifications, or by replying with an HTTP "307 temporary redirect" error response pointing to new NF service consumer, or by replying with another HTTP error such as an "404 Not found".
4.7 HATEOAS
4.7.1 General
As defined in [14], HATEOAS stands for Hypermedia As The Engine Of Application State. It means that the hypermedia models application state transitions and describe application protocols.
As defined in [15] clause 3 RESTful Domain Application Protocols, an application is a software implementation defined to achieve a particular goal. It consists of a set of constrained interactions between NF Service Consumer and Producer performed at run-time that are guided by an application specific set of rules. The application transits across some intermediate states until the application’s goal is achieved. The application has then reached its final state.
An application state is a snapshot of an application instance.
On each interaction, the NF Service Consumer and Producer exchange representations of resource state. According to [14], "REST concentrates all of the control state into the representations received in response to interactions." and "The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations." After each interaction the NF Service Consumer is then presented with control state options to interact with additional resources. These control states are in the form of hypermedia markups embedded in the returned resource representation. The application state changes when an NF Service Consumer examines and chooses which control to operate and subsequently interacts with the resources identified in the selected control state.
HATEOAS support is optional. If HATEOAS is supported, the procedure in the present clause 4.7 shall apply.
4.7.2 3GPP hypermedia format
4.7.2.1 Basic 3GPP hypermedia format
NOTE 1: Basic 3GPP hypermedia format is derived from Hypertext Application Language (HAL). HAL is specified in an expired internet draft available at "https://tools.ietf.org/html/draft-kelly-json-hal-08".
Basic 3GPP hypermedia format specifies the following optional reserved properties (see 3GPP TS 29.571 [5] for the complete list and definition of objects and object members):
– "_links": contains links to other resources and expresses valid state transitions.
A NF service producer shall construct a basic 3GPP hypermedia document by taking a 3GPP defined JSON object attribute list and then adding a "_links" attribute.
Table 4.7.2.1-1: _links attribute
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
_links |
map(LinksValueSchema) |
C |
0..N |
_links attribute to be added into the JSON hypermedia object definition |
The LinksValueSchema data type shall be added to the list of re-used data types of the hypermedia enabled API (see 3GPP TS 29.509 [21] for an example of implementation of a hypermedia API).
NOTE 2: Depending of the applicable situation, the presence condition and the cardinality can be changed in accordance. LinksValueSchema data type is defined in 3GPP TS 29.571 [5].
The "_links" member names are link relation types (as defined by IETF RFC 8288 [11]) and values are either a "link" object or an array of "link" objects.
Basic 3GPP hypermedia format specifies the following "link" attribute:
– "href": contains the URI of the linked resource.
A NF service producer shall set the Content-Type HTTP header to "application/3gppHal+json" when returning an HTTP payload with a basic 3GPP hypermedia enabled document.
A NF service consumer supporting HATEOAS shall advertise it by adding an "Accept" HTTP header with "application/3gppHal+json" as media type.
NOTE 3: The HATEOAS principle relies on NF Service Producer providing control state options (_links objects) embedded in the returned resource representation to the NF Service Consumer. An NF Service Consumer may decide to use the format of the _links attribute in HTTP requests to transfer URIs. This is beyond the scope of HATEOAS and another content type than "3gppHal+json" such as "application/json" can be used.
4.7.2.2 Extended 3GPP hypermedia format
NOTE 1: Extended 3GPP hypermedia format is derived from HAL-FORMS media type, see "https://rwcbook.github.io/hal-forms/".
Extended 3GPP hypermedia format specifies the following optional reserved properties (see 3GPP TS 29.571 [5] for the complete list and definition of objects and object members):
– "_links": contains links to other resources and expresses valid state transitions;
– "_templates": contains the HAL templates corresponding to the _links attribute.
A NF service producer shall construct a extended 3GPP hypermedia document by taking a 3GPP defined JSON object attribute list and then adding "_links" attribute and "_templates" attribute.
Table 4.7.2.2-1: _halForms attribute
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
_links |
map(Link) |
C |
1..N |
The key is the name of the link relation type. |
|
_templates |
map(HalTemplate) |
C |
1..N |
The key is the name of the corresponding link relation type to which the template is to be applied. |
The Link data type and HalTemplate data type shall be added to the list of re-used data types of the hypermedia enabled API.
NOTE 2: Depending of the applicable situation, the presence condition can be changed in accordance. Link and HalTemplate data types are defined in 3GPP TS 29.571 [5].A NF service producer shall set the Content-Type HTTP header to "application/3gppHalForms+json" when returning an HTTP payload with Extended 3GPP hypermedia enabled document.
A NF service consumer supporting HATEOAS and extended 3GPP hypermedia shall advertise it by adding an "Accept" HTTP header with "application/3gppHalForms+json" as media type.
4.7.3 Advertising legitimate application state transitions
When a NF service producer responds to a NF service consumer and there is one or more application state transition possible, the NF service producer shall advertise them by adding a "_links" property in the returned resource representation. When there are multiple state transitions with different relation types, then one member per relation type shall be added to the "_links" object which name is equal to the relation type. If there is only one state transition for a given relation type then the value of the member is a "link" object otherwise it is an array of "link" objects.
A NF service producer shall include a link into the returned resource representation with a registered relation type "self" when it is expected further actions upon it (for instance reading it again or replacing the resource state).
NOTE 1: For a hypermedia application, a returned representation without any link denotes for the NF service consumers the end of the interaction with the NF service producer. 3GPP APIs does not fulfil this rule.
4.7.4 Inferring link relation semantic
When a NF service consumer receives a response with linked resources then it shall infer the link relation semantic from the relation type. It shall not infer it from the linked resource URI format.
In 3GPP hypermedia, relation types are the name of "_links" object members.
4.7.5 Common Relation Types
4.7.5.1 Introduction
This clause contains the list of relation types supported in 3GPP Service Based Interface APIs.
As defined in IETF RFC 8288 [11] clause 2.1, a link relation type identifies the semantics of a link. It describes how resources are related to each other. It may also be used to indicate that the target resource of a link has particular attributes, or exhibits particular behaviours. Relation types shall not be confused with media types. It does not identify the format of the representation that results when the link is dereferenced.
There are two kinds of relation types:
– Registered relation types;
– Extension relation types.
Registered relation types are identified by a token (for instance "self") and can be reused by other applications such as 3GPP SBI APIs. They are registered by IANA. Registered relation types shall be preferred against extension relation types when expressing the link relation between two resources.
If there is a need to define a relation type that does not correspond to a registered one but it is not wanted to register it then an extension relation type shall be used instead.
4.7.5.2 Registered relation types
The "Link Relations" registry is located at: https://www.iana.org/assignments/link-relations.
Table 4.7.5.2-1 specifies the list of registered relation types supported by all hypermedia enabled 3GPP APIs.
Table 4.7.5.2-2 specifies the list of registered relation types that can be used by some hypermedia enabled 3GPP APIs, depending on the API design.
Table 4.7.5.2-1: mandatory registered relation types
|
Relation name |
|
self |
Table 4.7.5.2-2: optional registered relation types
|
Relation name |
|
next |
|
first |
|
previous |
|
last |
|
item |
4.7.5.3 Extension relation types
When no registered relation exists to express the relation between two resources, an extension relation type shall be used instead. It may be defined as a string token or as a URI as defined in IETF RFC 8288 [11].
An API specification using extension relation types shall contain a clause "Relation types" in the clause "Simple data types and enumerations" (see 3GPP TS 29.509 [21] for an example of implementation of a hypermedia API). The clause shall contain a table listing the token or the URI of the created relation types. It shall also contain a detailed specification of the semantic of the relation types defining the conditions that the NF Service Consumer shall match to follow a link.
4.7.6 Negotiating the support of optional HATEOAS features
The supported feature mechanism in clause 6.6.2 of 3GPP TS 29.500 [2] should be used to negotiate the usage of optional HATEOAS features in addition to negotiating the content type "3gppHal+json" and "3gppHalForms+json". Separate supported features can be defined for link relation types related to different use cases.
4.8 Error Responses
4.8.1 Error Response Status Code
When an error occurs that prevents the NF/NF service acting as an HTTP server from successfully fulfilling the HTTP request, the NF/NF service shall map an application error to the most similar 4xx/5xx HTTP status code as defined in clause 5.2.7 of 3GPP TS 29.500 [2].
4.8.2 Error Response Body
When the HTTP status code is not enough for the NF/NF service acting as an HTTP client to determine the cause of the error, the NF/NF service acting as an HTTP server should provide additional application related error information, by including in the response body a representation of a "ProblemDetails" data structure according to IETF RFC 7807 [19] that provides additional details of the error.
NOTE 1: The response body with the "ProblemDetails" data structure does not need to be sent on a 3GPP 5GC API for a particular HTTP status code if that HTTP status code itself provides enough information of the error, or if there are security concerns disclosing detailed error information.
The definition of the general "ProblemDetails" data structure from IETF RFC 7807 [19] is specified in clause 5.2.4.1 of 3GPP TS 29.571 [5]. The "ProblemDetails" data structure is a JSON object, as defined in IETF RFC 7807 [19], and contains the following attributes:
a) "type" – a URI reference according to IETF RFC 3986 [9] that identifies the problem type;
b) "title" – a short, human-readable summary of the problem type that should not change from occurrence to occurrence of the problem;
c) "status" – the HTTP status code for this occurrence of the problem;
d) "detail" – a human-readable explanation specific to this occurrence of the problem; and
e) "instance" – a URI reference that identifies the specific occurrence of the problem.
A particular API may define additional attributes that provide more information about the error.
NOTE 2: IETF RFC 7807 [19] allows adding of new properties in the "ProblemDetails" object.
The following additional attributes are generic extensions defined for the 3GPP 5GC APIs:
a) "cause"- a machine-readable application error cause specific to this occurrence of the problem; and
b) "invalidParams" – invalid parameters causing a request to be rejected.
The "cause" attribute should be included and provide application-related error information, if available. Application error causes should be defined in 5GC SBI APIs specifications, using the UPPER_WITH_UNDERSCORE case convention specified in clause 5.1.1.
EXAMPLE 1: "OUT_OF_LADN_SA".
The "invalidParams" attribute should be used to report invalid parameters when a request is rejected due to invalid parameters.
All the application error causes supported by an API should be defined in a specific clause "Application Errors" under the "Error Handling" clause specified for the API. The application error causes that a specific service operation may respond should be further listed in the table defining the data structure supported by the response body, with the associated HTTP error status code.
To enable a SEPP or an SCP for Indirect Communications to provide error details in error responses they originate, all service operations should support returning error responses including a representation of a "ProblemDetails" data structure. If additional application specific information is required in the error responses, the API should support returning the additional applicative information as specified in clause 4.8.3.The NF/NF service that generates the HTTP response shall include in the HTTP response a "Content-Type" header field set to:
– "application/problem+json", if the response includes a payload body containing the "ProblemDetails" (or extended ProblemDetails, see clause 4.8.3) data structure; or
– "application/json", if the response includes a payload body containing an application-specific data structure.
NOTE 3: Designing an error response payload body containing an application-specific data structure is discouraged for new APIs or service operations as this prevents a SEPP or an SCP when using indirect communications to include error details for errors they originate. If an API is defined with an application-specific error response body, the API also needs to support an error response body encoding a ProblemDetails object.
4.8.3 Extending ProblemDetails for API Backward Compatibility
For a service operation that returns "ProblemDetails" in error responses in a given release, if in a later release it is required to provide additional application specific information in the error responses, the API should be modified to return an Extended-ProblemDetails data type by reusing the "ProblemDetails" common data type, as specified in clause 5.3.17, to keep the API backward compatibility.
The "Content-Type" header shall be set to "application/problem+json" for the error response with the payload body containing the Extended-ProblemDetails data type define above.
EXAMPLE:
– an "AdditionInfo<ServiceOperation>" structured data type containing the additional information to be returned, as specified in clause 5.2.4.2:
Table 4.8.3-1 Definition of type AdditionInfo<ServiceOperation>
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
<attributes of additional information> |
"<type>" or "array(<type>)" or "map(<type>)" or "Any Type" |
"M", "C" or "O" |
"0..1", "1" or "M..N" |
<only if applicable> |
– a "ProblemDetails<ServiceOperation>" data type as combination of "ProblemDetails" common data type and "AdditionInfo<ServiceOperation>" data type define above, as specified in clause 5.2.4.5:
Table 4.8.3-2 Definition of type ProblemDetails<ServiceOperation> as a list of to be combined data types
|
Data type |
Cardinality |
Description |
Applicability |
|
ProblemDetails |
1 |
<only if applicable> |
|
|
AdditionInfo<ServiceOperation> |
1 |
<only if applicable> |
Example OpenAPI specification of ProblemDetails<ServiceOperation> data type, as specified in clause 5.3.10:
components:
schemas:
ProblemDetails<ServiceOperation>:
allOf:
– $ref: ‘TS29571_CommonData.yaml#/components/schemas/ProblemDetails’
– $ref: ‘#/components/schemas/AdditionInfo<ServiceOperation>’
Example OpenAPI specification of an error response returning ProblemDetails<ServiceOperation> data type:
responses:
‘504’:
description: Gateway Timeout
content:
application/problem+json:
schema:
$ref: ‘#/components/schemas/ProblemDetails<ServiceOperation>’
4.9 Transferring multiple resources to a NF Service Consumer
4.9.1 General
This clause describes some possible options that an API may implement when a NF Service Producer needs to return the representations of multiple resources to a NF Service Consumer, e.g. during the query of a large collection of resources (see clause 4.6.1.1.2.2).
Which options an API may support is defined in the respective stage 3 specification of the API.
4.9.2 Direct Delivery
A NF Service Producer may return the representations of the resources directly in the response body, i.e. the response body contains an array of the resource representations.
4.9.3 Direct Delivery with Iterations
If a large number of resource representations need to be returned, the NF Service Producer may return a representation containing a partial list of the requested resources in the response body, with link(s) containing URI(s) allowing the client to retrieve the remaining part(s) of the resources.
The returned representation containing a partial list of the requested resource is a "3gppHal+json" document. The document is a JSON object with two members whose names are below.
– _links.
– child: contains the resources of the partial list.
The member whose name is "_links" shall contain a member whose name is "self" and whose value is a "link" object that contains the URI of the returned representation. It shall also contain a member whose name is "next" and whose value is a "link" object that contains the URI of the next partial list of the collection if the returned partial list is not the last one.
The member whose name is "_links" should also contain members whose names are "first", "previous" and "last" and whose values contain a "link" object that contains the URIs of the first, previous and last partial lists of the collection if such lists exist.
The returned representation shall have a member whose name is "child" and whose value is an array of objects. Each of the individual resource representations returned in the partial list shall be embedded in an object of that array. Each object shall also have a member whose name is "_links". The later shall contain a member whose name is "self" and whose value is a "link" object that contains the URI of the embedded representation.
The table below provides a template to be added in the clause describing the GET operation of a 3GPP API using the direct delivery with iteration mechanism.
Table 4.9.3-1: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
PartialList |
M |
1 |
200 OK |
This case represents a successful return of a partial list for the corresponding request with direct delivery with iteration. |
The following data types shall be added to the list of specific data types and described as below in the structured data type clause.
Table 4.7.2-1: PartialList
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
_links |
map(LinksValueSchema) |
M |
1..N |
contains the pagination links |
|
child |
array(ApiSpecificHypermediaEnabledIndividualResource) |
M |
1..N |
contains the individual resources with a self link. The data type in the array is specific to the API and is a hypermedia enabled version of the individual resource data type. |
Table 4.7.2-1: ApiSpecificHypermediaEnabledIndividualResource
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
attribute1 |
||||
|
attribute2 |
||||
|
… |
||||
|
attribute N |
||||
|
_links |
selfLink |
M |
1 |
contains the link to itself |
NOTE 1: attributes 1 to N are the attributes of the original individual resource.
The LinksValueSchema and SelfLink data types shall be added to the list of re-used data types of the 3GPP API.
A NF Service Consumer that receives link(s) in the response body may retrieve the remaining part(s) of the resources by sending GET requests towards the URI(s) contained in the link(s).
4.9.4 Indirect Delivery
A NF Service Producer may not return any requested resource representation and instead may return a representation containing only a list of links to the requested resources in the response body.
The returned representation containing the list is a "3gppHal+json" document. The document is a JSON object with one member whose name is:
– _links.
This member shall contain a member whose name is "item" and whose value is an array of "link" objects. Each of the link objects contains one requested resource URI. There shall be one link object per requested resource.
It shall also contain a member whose name is "self" and whose value is a "link" object that contains the URI of the returned representation.
A NF Service Consumer that receives such a response may then send a GET request per resource URI to retrieve the requested resources from the NF Service Producer.
4.9.5 Indirect Delivery with HTTP/2 Server Push
A NF Service Producer may use HTTP/2 Server Push, if HTTP/2 Server Push is supported in the PLMN.
To use HTTP/2 Server Push, the NF Service Producer shall send PUSH_PROMISE frames in the HTTP response, with each PUSH_PROMISE frame containing a GET request targeting the URI of one resource to be transferred and the reserved stream identifier to be used for transferring the resource. Then the NF Service Producer shall send Push Responses via the corresponding reserved streams, with each Push Response containing the representation of the associated resource. The NF Service Producer shall also send links with the URIs of the resources in DATA frame(s) of the response message.
A NF Service Consumer may disable HTTP/2 Server Push by sending SETTINGS_ENABLE_PUSH parameter with value "0" on HTTP level, as specified in IETF RFC 7540 [13].
Figure 4.9.5-1 Indirect Delivery with HTTP/2 Server Push
1. A NF Service Consumer sends a HTTP request to get resources(s) to the NF Service Producer, e.g. a query of a collection of resources.
2. The NF Service Producer detects that multiple resources are to be returned and choose to indirectly deliver the resources with the Server Push mechanism.
3. The NF Service Producer returns multiple PUSH_PROMISE Requests before HEADERS frame and DATA frames(s) to the NF Service Consumer. Each PUSH_PROMISE Request contains the URI of one resource to be transferred and the identifier of the reserved stream used for transferring the resource. The NF Service Producer shall also send links with the URIs of the resources in DATA frame(s) of the response message.
4.1-4.n. The NF Service Producer sends Push Reponses via corresponding reserved streams. Each Push Response contains the representation of the associated resource.
5. If the NF Service Consumer does not successfully receive a resource in time, it may send a request to get that resource, using the resource URI previously received from the Push Request.
5.a. The NF Service Producer returns the data of the requested resource in the response.
4.9.6 Criteria for choosing the transfer method
The following considerations may be used to determine which method to use transfer multiple resources to a NF Service Consumer.
If the size of the representation of each resource is small, direct delivery is preferred. If the number of resources to be returned is large, the NF Service Producer may choose iterative delivery.
NOTE 1: For this release of this specification, a JSON payload size less than 64000 octets is considered as not large and a JSON payload size larger than 64000 octets is considered as large.
If the size of the representation of each resource is large, indirect delivery is preferred. If the NF Service Producer supports HTTP/2 Server Push, then:
– when SETTINGS_ENABLE_PUSH parameter with value "1" has been received from the NF Service Consumer, as specified in IETF RFC 7540 [13], it should choose HTTP/2 Server Push to deliver the resource.
– when SETTINGS_ENABLE_PUSH parameter with value "0" has been received from the NF Service Consumer, as specified in IETF RFC 7540 [13], it must not choose HTTP/2 Server Push to deliver the resources.
– when SETTINGS_ENABLE_PUSH parameter has not been received from the NF Service Consumer, as specified in IETF RFC 7540 [13], it may decide whether to use HTTP/2 Server push or not, depending on other factors, e.g. operator policy, whether the client and server pertain to the same PLMN, etc.
An NF Service Producer shall use Indirect Delivery with HTTP/2 Server Push only if the NF Service Consumer (client) indicated support for accepting server pushed resource representations, via the Supported Features negotiation as specified in clause 6.6.2 of 3GPP TS 29.500 [2].
NOTE 2: In this release the Indirect Delivery with HTTP/2 Server Push is not used by 3GPP service based interface APIs.