Tech-invite  3GPPspace  IETF RFCs  SIP
index  21  22  23  24  25  26  27  28  29  31  32  33  34  35  36  37  38  4‑5x

Content for  TS 29.501  Word version:  18.0.0

Top   Top   Up   Prev   Next
1…   4…   4.6…   4.7…   5…   5.3…   6…   A… 
4 Design Principles for 5GC SBI APIs  4.1 General Principles  4.2 API Design Style and REST Implementation Levels  4.3 Version Control  4.3.0 General  4.3.1 Structure of API version numbers  4.3.1.1 API version number format  4.3.1.2 Rules for incrementing field values  4.3.1.3 Visibility of the API version number fields  4.3.1.4 Relation to the Technical Specification version number  4.3.1.5 Discovery of the supported versions  4.3.1.6 Withdrawing API versions  4.4 URI Structure  4.4.1 Resource URI structure  4.4.2 Custom operations URI structure  4.4.3 Callback URI structure  4.5 Resource Representation and Content Format Negotiation  4.5.1 Resource Representation  4.5.2 Content Format Negotiation 
...

 

4  Design Principles for 5GC SBI APIs  p. 10

4.1  General Principles  p. 10

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 RFC 8259);
  • 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 TS 29.500 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.
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 TS 29.500 and should be referenced from individual 5GC SBI API specifications.
Common data types applicable to several 5GC SBI API specifications should be defined in TS 29.571 and should be referenced from individual 5GC SBI API specifications.
Up

4.2  API Design Style and REST Implementation Levels  p. 11

4.2.1  General  p. 11

5GC SBI API specifications should apply a protocol design framework as follows:
  1. 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;
  2. 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;
  3. it is possible to mix REST-style operations and RPC-style operations in the same API.
Up

4.2.2  API Design Principles for Query Operation  p. 11

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:
  1. 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);
  2. 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);
  3. standard HTTP GET method shall not be used for non-safe operations and non-idempotent operations.
Up

4.2.3  API Design Principles for Delete Operation  p. 11

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:
  1. 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);
  2. 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);
  3. standard HTTP DELETE method shall not be used for non-idempotent operations.
Up

4.3  Version Control  p. 12

4.3.0  General  p. 12

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.

4.3.1  Structure of API version numbers  p. 12

4.3.1.1  API version number format  p. 12

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-]).
EXAMPLES:
"1.0.0-alpha.1"
"3.0.1+orange.2020-09"
Up

4.3.1.2  Rules for incrementing field values  p. 12

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:
    1. there are one or more backward incompatible changes to the API after the OpenAPI freeze for a given 3GPP Release; and
    2. 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".
  • If a backward incompatible change needs to be applied to several 3GPP Releases the following applies:
    1. 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".
    2. 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.
      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".
    3. 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:
    1. 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.
    2. 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)
    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:
    1. 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
    2. 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.
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:
      1. When the 1st or 2nd field is incremented before the OpenAPI freeze of a 3GPP Release, this field shall obtain the value "alpha.1".
      2. 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.
Up

4.3.1.3  Visibility of the API version number fields  p. 15

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

4.3.1.4  Relation to the Technical Specification version number  p. 15

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

4.3.1.5  Discovery of the supported versions  p. 16

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 TS 29.510 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 TS 29.510. The NRF shall notify as specified in clause 5.2.2.6 of TS 29.510, 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.
Up

4.3.1.6  Withdrawing API versions  p. 16

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.
Withdrawn API versions should not be deployed.
Up

4.4  URI Structure  p. 16

4.4.1  Resource URI structure  p. 16

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")
  • the fixed string "://"
  • authority (host and optional port) as defined in IETF RFC 3986. The host should be represented by the operator specific FQDN (for FQDN examples see clause 28.3.2 in TS 23.003).
  • 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 TS 29.502:
  • url: '{apiRoot}/nsmf-pdusession/v1'
Up

4.4.2  Custom operations URI structure  p. 17

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

4.4.3  Callback URI structure  p. 17

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 Section 4.3 of RFC 3986, 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 RFC 5234):
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.
Up

4.5  Resource Representation and Content Format Negotiation  p. 18

4.5.1  Resource Representation  p. 18

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 RFC 7231. 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.
Up

4.5.2  Content Format Negotiation  p. 18

RFC 7231 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.
Up

Up   Top   ToC