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 29.501  Word version:  18.4.0

Top   Top   Up   Prev   Next
1…   4…   4.3…   4.4…   4.6…   4.6.2…   4.7…   4.8…   4.9…   4.10   5…   5.2…   5.3…   6…   A…   D   E… 
4 Design Principles for 5GC SBI APIs  4.1 General Principles  4.2 API Design Style and REST Implementation Levels  4.2.1 General  4.2.2 API Design Principles for Query Operation  4.2.3 API Design Principles for Delete Operation 
...

 

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

Up   Top   ToC