Tech-invite3GPPspecsSIPRFCs
Overview21222324252627282931323334353637384‑5x

Content for  TS 29.501  Word version:  16.4.0

Top   Top   Up   Prev   None
1…   4…   4.6…   4.7…   5…   5.3…   6…   A…

 

A  TS Skeleton TemplateWord‑p. 66
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:
https://www.3gpp.org/ftp/information/All_Templates/29.xxx-SBI-Stage3-Template.zip
B  Backward Incompatible Changes
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 TS 29.500, clause 6.6.2), 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.
Backward incompatible changes are additions or changes in the API that break the existing Service Consumer behaviour. Here is a list of backward incompatible changes that shall require incrementing the 1st field (MAJOR) of the API version number unless they only relate to smaller and optional parts of the functionality (see above):
  • 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.
Up
C  Resource modellingWord‑p. 67
C.0  General
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.
Up
C.1  Document
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 (see clause X.4) with the URI of the resource.
Up
C.2  Collection
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.
Up
C.3  StoreWord‑p. 68
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.
Up
C.4  Custom operation
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 chapter 4.4.2: /{custOpName}.
Up
D  Example of an OpenAPI specification file for Patch
As described in clause 4.6.1.1.3.2, the bodies of HTTP PATCH requests will either use a "JSON Merge Patch" encoding as defined in IETF RFC 7396 [7], or a "JSON Patch" encoding as defined IETF RFC 6902 [8]. This annex provides an example OpenAPI Specification [4] allowing both encodings.
openapi: 3.0.0
info:
  version: "1.0.0"
  title: PATCH Example
paths:
  /inventory:
    post:
      summary: adds an inventory item
      operationId: addInventory
      description: Adds an item to the system
      responses:
        '201':
          description: item created
        '400':
          description: 'invalid input, object invalid'
        '409':
          description: an existing item already exists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryItem'
        description: Inventory item to add
  /inventory/{id}:
    get:
      summary: read inventory item
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: search results matching criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItem'
        '400':
          description: bad input parameter
    patch:
      summary: patch inventory item
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PatchInventoryItem'
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/MergePatchInventoryItem'
      responses:
        '200':
          description: Patch was succesfull and updated Inventory Item is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItem'
        '204':
          description: Patch was succesfull
        '400':
          description: bad input parameter
components:
  schemas:
    InventoryItem:
      type: object
      required:
        - name
        - manufacturer
      properties:
        id:
          type: integer
        name:
          type: string
        manufacturer:
          $ref: '#/components/schemas/Manufacturer'
        customers:
          type: array
          items:
            type: string
    Manufacturer:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        homePage:
          type: string
          format: url
        phone:
          type: string
    PatchInventoryItem:
      type: array
      description: A JSON PATCH body schema to Patch selected parts of an Inventory Item
      items:
        anyOf:
          - oneOf:
            - type: object
              description: Modifies the URL of a Manufacturer
              properties:
                op:
                  type: string
                  enum:
                    - "add"
                    - "remove"
                    - "replace"
                path:
                  type: string
                  pattern: '^\/manufacturer\/homePage$'
                value:
                  type: string
                  format: url
              required:
                - "op"
                - "path"
            - type: object
              description: Modifies a Manufacturer
              properties:
                op:
                  type: string
                  enum:
                    - "replace"
                path:
                  type: string
                  pattern: '^\/manufacturer$'
                value:
                  $ref: '#/components/schemas/Manufacturer'
              required:
                - "op"
                - "path"
                - "value"
            - type: object
              description: Modifies a Customer
              properties:
                op:
                  type: string
                  enum:
                    - "add"
                    - "remove"
                    - "replace"
                path:
                  type: string
                  pattern: '^\/customers\/(-|\d+)$'
                value:
                  type: string
              required:
                - "op"
                - "path"
          - type: object
            description: Open Alternative
        minItems: 1
    MergePatchInventoryItem:
      description: A JSON Merge PATCH body schema to Patch selected parts of an Inventory Item
      type: object
      properties:
        manufacturer:
          $ref: '#/components/schemas/Manufacturer'
          nullable: true
        customers:
          type: array
          description: Allows to replace the entire array, but not to modify individual elements.
          items:
            type: string
Up
$  Change historyWord‑p. 72

Up   Top