Content for TS 29.501 Word version: 18.4.0
A TS Skeleton Template
B Backward Incompatible Changes
C Resource modelling
C.0 General
C.1 Document
C.2 Collection
C.3 Store
C.4 Custom operation
...
...
A TS Skeleton Template p. 75
A TS Skeleton Template to be used as a starting point of drafting a 5G System SBI Stage 3 specification is available at the following location:
B Backward Incompatible Changes p. 75
This Annex provides information about the changes in the API that are considered as backwards compatible and those that are considered as backwards incompatible. This list is to be considered informative and it may be expanded in future releases, when necessary.
Backward compatible changes are additions or changes in the API that do not break the existing Service Consumer behaviour. Examples of backward compatible changes include:
- Adding a new, optional child resource/URI;
- Supporting a new HTTP method;
- Adding new elements to a resource representation;
- Changing the order of fields in a resource representation;
- Addition of a new status code:
- Corrections of obvious errors in an OpenAPI file required to enable a correct parsing of the file such as misspelled references;
- Corrections that only relate to smaller and optional parts of the functionality (e.g. a supported feature, see clause 6.6.2 of TS 29.500), even if the changes are backward incompatible with respect to that part of the functionality; and
- Backward-compatible changes related to the semantics (i.e. functional behaviour) specified for an API.
- Removing a resource/URI:
- Removing support for an HTTP method;
- Renaming a field in a resource representation;
- Adding mandatory parameters to a resource URI or resource representation;
- Attribute data type changes;
- Cardinality changes (NOTE 3); and
- Backward incompatible changes related to the semantics (i.e. functional behaviour) specified for an API.
C Resource modelling p. 76
C.0 General p. 76
When designing an API, one shall first think of defining the set of resources consumed. Resources represent objects that are modified by standard HTTP methods and that can be modelled with one of 4 archetypes detailed below. Resource archetypes help API designers to structure the resources. In this process the designer should refer to the appropriate archetype when the resource definition perfectly matches the archetype one. Referring to an archetype immediately defines what operations and HTTP methods are supported by the resource.
The archetypes provided hereafter don't preclude the existence of resources of different types.
C.1 Document p. 76
The document archetype is the conceptual base archetype of the other ones. Any resource that is not identified with one of the other resource archetypes is a document.
A document may have child resources that represent its specific subordinate concepts.
The archetype does not place any restriction on HTTP methods when acting on a document.
Only CRUD operations are performed directly on a document resource, i.e. by sending an HTTP request to the URI of that resource. Custom methods are not performed directly on the resource, but by sending an HTTP request to a URI that is associated by a convention with the URI of the resource.
C.2 Collection p. 76
The collection archetype can be used to model a resource that serves as a directory of resources. A collection is NF Service Provider-managed so the NF Service Provider decides the URIs of each resource that is created in the collection.
The Create and Read operations are performed on a collection directly.
More specifically:
- A collection child resource is created by sending a POST with the collection URI if accepted by the collection;
- A collection is read by sending a GET with the collection URI;
- The PUT and PATCH methods with the collection URI are not allowed;
- The DELETE method with the collection URI is only allowed if the collection resource has been created dynamically based on a request from the NF Service Consumer.
- The authorized operations on a collection child resource depend on that resource's archetype.
C.3 Store p. 77
The store archetype can also be used to model a resource that serves as a directory of resources but a store is NF Service Consumer-managed. The NF Service Consumer solely decides what resource shall be added to / deleted from a store. The NF Service Consumer decides what the URI of the added resource is.
The Read operation is performed on a store directly, and the Create operation is performed on store child resources.
More specifically:
- A store child resource is created by sending a PUT with the URI of the child resource to be created.
- A store is read by sending a GET with the store URI;
- The POST, PUT and PATCH methods with the store URI are not allowed;
- The DELETE method with the store URI is only allowed if the store resource has been created dynamically based on a request from the NF Service Consumer.
- Apart from Create (PUT), the authorized operations on a store child resource depend on that resource's archetype.
C.4 Custom operation p. 77
The custom operation archetype can be used to model an unsafe and non-idempotent operation that is not a Create on a collection.
A custom operation does not operate directly on the resource that would be identified by the custom operation URI. Instead, when the custom operation is associated with a resource, the operation is performed on this associated resource. For instance, a custom operation may modify the associated resource in a special way. This associated resource is identified by stripping the suffix string "/<custOpName>" from the custom operation URI template in clause 4.4.2.
When the custom operation is not associated with any resource but with the service, it acts as an executable function with input parameters and returns the result of the executed function in the response body, not modifying any resource.
POST is the only method allowed with a custom operation URI.
The semantic of the custom operation is encoded in the last segment of the URI template in clause 4.4.2: /{custOpName}.
