Content for TS 26.517 Word version: 18.4.0
9 MBS AF APIs (MBS-5)
9.1 General
9.2 User Service Description retrieval API
9.2.1 General
9.2.2 Resource structure
9.2.3 Response format
...
...
9 MBS AF APIs (MBS-5) p. 37
9.1 General p. 37
This clause specifies the network APIs exposed by the MBS AF with reference to the general provisions of clause 8 as they apply to the reference point in question.
9.2 User Service Description retrieval API p. 37
9.2.1 General p. 37
In the case where Service announcement modes (see Table 4.5.3-1 of TS 26.502) indicates that the MBS User Service Announcement for an MBS User Service is advertised at reference point MBS-5, the User Service Description retrieval API is used by the MBSF Client to retrieve a User Service Descriptions Bundle from the MBS AF that enable reception of the MBS User Service(s) to be initiated by the MBSF Client.
In the case where Service announcement modes (see Table 4.5.3-1 of TS 26.502) indicates that the MBS User Service Announcement for an MBS User Service is advertised via the User Service Announcement Channel at reference point MBS-4-MC, the User Service Description retrieval API is used by the MBSF Client at reference point MBS-7' to retrieve a User Service Descriptions Bundle from the MBSTF Client that enable reception of the MBS User Service(s) to be initiated by the MBSF Client.
In the absence of prior knowledge about which Service announcement mode(s) are configured for currently provisioned MBS User Services, an MBSF Client may use either or both of the above procedures to proactively retrieve User Service Descriptions Bundles.
9.2.2 Resource structure p. 37
The User Service Description retrieval API is accessible from the MBS AF at reference point MBS-5 and from the MBSTF Client at reference point MBS-7' through the following URL base path:
{apiRoot}/3gpp-mbs-user-service-discovery/{apiVersion}/
The operations and the corresponding HTTP methods in Table 9.2.2-1 are supported through the above API base path. In each case, the sub-resource path specified in the second column shall be appended to the URL base path. The provisions of clause 8.2.3.4 shall apply to all operations.
| Operation | Sub-resource path | Allowed HTTP method(s) | Description |
|---|---|---|---|
| Discover User Service Descriptions | user-service-descriptions?{queryParameters} | GET | Used to discover a set of User Service Descriptions that match a set of filtering criteria corresponding to at least one of the query parameters specified in Table 9.2.2-2. Multiple query parameters may be concatenated using the ampersand ('&') character as a separator with the resulting semantics of logical conjunction (i.e., Boolean AND). It is an error to invoke this operation with no query parameters. A User Service Descriptions Bundle (see clause 9.2.3.1) is returned containing User Service Descriptions matching all of the specified filtering criteria and their dependent resources, which may be empty if none match all of the criteria. |
| Retrieve User Service Description | user-service-descriptions/{externalServiceId} | GET | The {externalServiceId} uniquely identifies a single User Service Description resource in the MBS AF. If the requested User Service is known to the MBS AF, a User Service Descriptions Bundle (see clause 9.2.3.2) is returned comprising a single User Service Description and its dependent resources. Otherwise, a suitable HTTP error response code is returned. |
Table 9.2.2-2 specifies the query parameters that may be combined with the operations specified in Table 9.2.2-1.
| Applicable operation | Filter name | Query parameter | Description |
|---|---|---|---|
| Discover User Service Descriptions | Service class | service-class={serviceClassTermId} | Used to select User Service Descriptions that are tagged with the supplied service class term identifier (see Table 4.5.3-1 of TS 26.502), which is expressed as a fully-qualified URI string from a controlled vocabulary (e.g., OMNA BCAST Service Class [25]) with appropriate URL encoding applied. |
| Conformance profile | profile={conformanceProfileTermId} | Used to select User Service Descriptions that include Distribution Session Descriptions tagged with the supplied conformance profile term identifier (see clause 12), which is expressed as a fully-qualified URI string from a controlled vocabulary (e.g., clause C.2) with appropriate URL encoding applied. |
9.2.3 Response format p. 38
9.2.3.1 User Service Descriptions result p. 38
The HTTP response message shall convey a User Service Descriptions Bundle Entity as specified in clause 5.3.1A in which the root body part is a User Service Descriptions document that includes a User Service Description for each User Service that matches the filtering criteria. This response message shall conform to the following requirements:
- The User Service Descriptions Bundle Entity shall include any dependent resources as additional body parts per clause 5.3.1A.
- The headers of the User Service Descriptions Bundle Entity shall be conveyed in the headers of the HTTP response message.
- A strong entity tag shall additionally be conveyed in the headers of the HTTP response per clause 8.2.3.4.
- The body of the User Service Descriptions Bundle Entity shall be conveyed in the body of the HTTP response message.
- The MBS AF may apply GZip [41] encoding to individual body parts of the User Service Descriptions Bundle Entity, or to the entity as a whole, subject to the provisions of clause 8.2.2.
9.2.3.2 User Service Description result p. 39
The HTTP response message shall convey a User Service Bundle Entity as specified in clause 5.3.1A in which the root body part is a User Service Descriptions document that includes a single User Service Description. This response message shall conform to the following requirements:
- The User Service Descriptions Bundle Entity shall include any dependent resources as additional body parts per clause 5.3.1A.
- The headers of the User Service Descriptions Bundle Entity shall be conveyed in the headers of the HTTP response message.
- A strong entity tag shall additionally be conveyed in the headers of the HTTP response per clause 8.2.3.4.
- The body of the User Service Descriptions Bundle Entity shall be conveyed in the body of the HTTP response message.
- The MBS AF may apply GZip [41] encoding to individual body parts of the User Service Descriptions Bundle Entity, or to the entity as a whole, subject to the provisions of clause 8.2.2.
