Tech-invite  3GPPspace  IETFspace
◀  ▶  21  22  23  24  25  26  27  28  29  31  32  33  34  35  36  37  38  4‑5x

Content for  TS 26.517  Word version:  18.4.0

Top   Top   Up   Prev   Next
1…   5…   6…   7…   8…   9…   10…   11…   12…   A…   D…   E… 
8 General aspects of APIs for MBS User Services  8.1 HTTP resource URIs and paths  8.2 Usage of HTTP  8.2.1 HTTP protocol version  8.2.2 HTTP message bodies for API resources  8.2.3 Usage of HTTP headers  8.3 HTTP response codes 
...

 

8  General aspects of APIs for MBS User Services  p. 33

8.1  HTTP resource URIs and paths  p. 33

The resource URI used in each HTTP request to the API provider shall have the structure defined in subclause 4.4.1 of TS 29.501, i.e.:
{apiRoot}/{apiName}/{apiVersion}/{apiSpecificResourceUriPart}
with the following components:
  • {apiRoot} shall be set as described in TS 29.501.
  • {apiName} shall be set as defined by the following clauses.
  • {apiVersion} shall be set to "v1" in this release.
  • {apiSpecificResourceUriPart} shall be set as described in the following clauses.
Up

8.2  Usage of HTTP  p. 33

8.2.1  HTTP protocol version  p. 33

8.2.1.1  General  p. 33

Content interfaces at reference points specified in the present document shall expose an HTTP/1.1 RFC 9112 endpoint to API clients. They may additionally expose an HTTP/2 RFC 9113 endpoint, including support for the HTTP/2 starting mechanisms specified in Section 3 of RFC 9113. The API client may choose any supported HTTP protocol version. TLS RFC 8446 shall be supported on these interfaces and, where the option to use cleartext HTTP is available in the version of HTTP selected by the API client, it should opt for HTTPS interactions in preference.
Up

8.2.1.2  MBSF  p. 33

The HTTP protocol version used to invoke Nmbsf service operations on the MBSF at reference point Nbm10 is specified in clauses 6.1.2.1 and 6.2.2.1 of TS 29.580.

8.2.1.3  MBSTF  p. 33

The HTTP protocol version used to invoke Nmbstf service operations on the MBSTF at reference point Nmb2 is specified in clause 6.1.2.1 of TS 29.581.
The endpoint exposed by the MBSTF to the MBSF at reference point Nmb2 for the purpose of pushing object manifests into the MBSTF shall comply with the general provisions specified in clause 8.2.1.1.
The endpoint exposed by the MBSTF to the MBS Application Provider (AF/AS) at reference point Nmb8 for the purpose of pushing objects into the MBSTF shall comply with the general provisions specified in clause 8.2.1.1.
Up

8.2.1.4  MBS AF  p. 33

The endpoint exposed by the MBS AF to the MBSF Client at reference point MBS-5 for the purpose of retrieving User Service Descriptions using the API specified in clause 9.2 shall comply with the general provisions specified in clause 8.2.1.1.
The endpoint exposed by the MBS AF to the MBSTF at reference point MBS-11 for the purpose of retrieving object manifests and User Service Descriptions shall comply with the general provisions specified in clause 8.2.1.1.
All responses from the MBS AF that carry a message body shall include a strong entity tag in the form of an ETag response header field and a modification timestamp in the form of a Last-Modified response header per Section 8.8 of RFC 9110.
All endpoints exposed by the MBS AF shall support conditional HTTP requests using the header fields If-none-Match and If-Modified-Since per Section 13 of RFC 9110.
Up

8.2.1.5  MBS AS  p. 34

The endpoint exposed by the MBS AS to the MBSTF Client at reference point MBS-4-UC for the purpose of unicast object repair shall comply with the general provisions specified in clause 8.2.1.1.
Byte range requests per Section 14 of RFC 9110 shall be supported by the MBS AS at reference point MBS-4-UC for the purpose of efficient unicast object repair by the MBSTF Client.
Up

8.2.1.6  MBSSF  p. 34

The endpoint exposed by the MBSSF to the MBSF Client at reference point MBS 10 for the purpose of MBS Service Key (MSK) retrieval shall comply with the general provisions specified in clause 8.2.1.1.
All responses from the MBSSF that carry a message body shall include a strong entity tag in the form of an ETag response header field and a modification timestamp in the form of a Last-Modified response header per Section 8.8 of RFC 9110.
All endpoints exposed by the MBSSF shall support conditional HTTP requests using the header fields If-none-Match and If-Modified-Since per Section 13 of RFC 9110.
Up

8.2.2  HTTP message bodies for API resources  p. 34

Individual APIs in the present document specify the syntax and encoding of HTTP request and response message bodies. MIME content types for a subset of these are registered in Annex E.
Message bodies compressed using GZip [41] content encoding may be returned by HTTP servers if the client indicates that this is acceptable per Section 12.5.3 of RFC 9110. In this case the content encoding is indicated as specified in Section 8.4 of RFC 9110.
Up

8.2.3  Usage of HTTP headers  p. 34

8.2.3.1  General  p. 34

Standard HTTP headers shall be used in accordance with clause 5.2.2 of TS 29.500, encoded appropriately for the version of HTTP in use.

8.2.3.2  User Agent identification  p. 34

8.2.3.2.1  General  p. 34
When one of the MBS User Services functions defined in TS 26.502 makes requests to an HTTP endpoint specified in the present document, it shall identify itself to the HTTP server using a User-Agent request header field (see Section 10.1.5 of RFC 9110) that includes a product identifier indicating the type of client function making the request in its token element.
The optional product-version suffix shall be present and should indicate the version number of the present document (without the leading "V") with which the client implementation complies and shall, at minimum, indicate the 3GPP release number with which the implementation complies.
The User-Agent request header field may also include comment elements (see Section 5.6.5 of RFC 9110) following the above specified product identifier, as well as additional vendor-specific product identifiers and comment elements compliant with the syntax and guidance provided in Section 10.1.5 of RFC 9110.
EXAMPLE 1:
MBSTF/17.4.0 (build2114) libhttp/1.23.2
EXAMPLE 2:
MBSFClient/17
Up
8.2.3.2.2  MBSF identification  p. 35
When invoking the Nmbstf service at reference point Nmb2, the MBSF identifies itself to the MBSTF using a User-Agent request header as specified in clauses 6.1.2.2.1 and 6.2.2.2.1 of TS 29.580.
8.2.3.2.3  MBSTF identification  p. 35
When ingesting content using the pull-based object acquisition method (see Table 4.5.6-2 of TS 26.502), the MBSTF shall identify itself to the MBS Application Provider (AF/AS) at reference point Nmb8 and to the MBS AF at reference point MBS-11 using a User-Agent request header field that complies with the general provisions specified in clause 8.2.3.2.1. The product identifier token shall be set to the value MBSTF.
Up
8.2.3.2.4  MBSF Client identification  p. 35
The MBSF Client shall identify itself to the MBS AF at reference point MBS-5 and to the MBSSF at reference point MBS-10 using a User-Agent request header field that complies with the general provisions specified in clause 8.2.3.2.1. The product identifier token shall be set to the value MBSFClient.
8.2.3.2.5  MBSTF Client identification  p. 35
The MBSTF Client shall identify itself to the MBS AS at reference point MBS-4-UC using a User-Agent request header field that complies with the general provisions specified in clause 8.2.3.2.1. The product identifier token shall be set to the value MBSTFClient.

8.2.3.3  Server identification  p. 35

8.2.3.3.1  General  p. 35
When one of the MBS User Services functions defined in TS 26.502 responds to an HTTP request, it shall identify itself to the requesting client using a Server response header (see Section 10.2.4 of RFC 9110) that includes a product identifier indicating the type and host name of the responding server in its token element. The server type and host name shall be separated by a single hyphen ('-') character.
The optional product-version suffix shall be present and should indicate the version number of the present document (without the leading "V") with which the server implementation complies and shall, at minimum, indicate the 3GPP release number with which the implementation complies.
The Server response header field may also include comment elements (see Section 5.6.5 of RFC 9110) following the above specified product identifier, as well as additional vendor-specific product identifiers and comment elements compliant with the syntax and guidance provided in Section 10.2.4 of RFC 9110.
EXAMPLE 1:
MBSTF-vm10665.mno.net/17.4.0 (api=1.0.0) libsbi/2.1 libnf/1.2
EXAMPLE 2:
MBSAF-vm10240.mno.net/17 (api=1.0.0) libsbi/2.1 libnf/1.2
Up
8.2.3.3.2  MBSF identification  p. 35
When responding to Nmbsf service operations made by the MBS Application Provider (AF/AS) at reference point Nmb10, the MBSF's Server response header is set as specified in clauses 6.1.2.2.1 and 6.2.2.2.1 of TS 29.580.
8.2.3.3.3  MBSTF identification  p. 35
When responding to Nmbstf service operations made by the MBSF at reference point Nmb2, the MBSTF's Server response header is set as specified in clause 6.1.2.2.1 of TS 29.581.
When acknowledging objects published using the push-based object acquisition method by the MBSF at reference point Nmb2 or by the MBS Application Provider (AF/AS) at reference point Nmb10, the MBSTF shall identify itself using a Server response header field that complies with the general provisions specified in clause 8.2.3.3.1. The product identifier token shall be set to the value MBSTF.
Up
8.2.3.3.4  MBS AF identification  p. 36
The MBS AF shall identify itself to the MBSF Client at reference point MBS-5 and to the MBSTF at reference point MBS-11 using a Server response header field that complies with the general provisions specified in clause 8.2.3.3.1. The product identifier token shall be set to the value MBSAF.
8.2.3.3.5  MBS AS identification  p. 36
The MBS AS shall identify itself to the MBSTF Client at reference point MBS-4-UC using a Server response header field that complies with the general provisions specified in clause 8.2.3.3.1. The product identifier token shall be set to the value MBSAS.

8.2.3.4  Support for conditional HTTP GET requests  p. 36

The provisions in clause 5.2.2 of TS 29.500 relating to conditional GET requests using the If-None-Match and If-Modified-Since request headers apply to all Network Functions in the MBS System. In particular:
All responses from the MBS AF at reference points MBS-5 and MBS-11 that carry a resource message body shall include:
All API endpoints on the MBS AF that expose the HTTP GET method shall support conditional requests using the If-None-Match and If-Modified-Since request headers per Section 13.1.2 of RFC 9110 and Section 13.1.3 of RFC 9110. API clients should not attempt to revalidate their cached copy of a resource using a conditional GET request before the indicated time-to-live period has elapsed.
Up

8.2.3.5  Support for conditional HTTP POST, PUT, PATCH and DELETE requests  p. 36

The provisions in clause 5.2.2 of TS 29.500 relating to conditional POST, PUT, PATCH and DELETE requests using the If-Match request header apply to all Network Functions in the MBS System. In particular:
Up
8.2.3.3.6  MBSSF identification  p. 36
The MBSSF shall identify itself to the MBSF Client at reference point MBS 10 using a Server response header field that complies with the general provisions specified in clause 8.2.3.3.1. The product identifier token shall be set to the value MBSSF.

8.3  HTTP response codes  p. 37

Guidelines for error responses to the invocation of APIs of NF services are specified in clause 4.8 of TS 29.501. API-specific error responses are specified in the respective technical specifications.

Up   Top   ToC