Tech-invite3GPPspaceIETF RFCsSIP

Content for  TS 23.222  Word version:  17.6.0

Top   Top   Up   Prev   Next
0…   4…   5   6…   6.3…   7…   8…   8.5…   8.9…   8.13…   8.17…   8.21…   8.25…   9…   10…   11…   A   B…   B.2   B.3   C…   D…


9  API consistency guidelinesp. 86

9.1  Generalp. 86

This clause specifies the API consistency guidelines for all northbound APIs utilizing CAPIF architecture. The guidelines are categorized as follows:
  • fundamental API guidelines, applicable to all northbound APIs utilizing CAPIF; and
  • architecture design considerations, applicable to all northbound APIs utilizing CAPIF.

9.2  Fundamental API Guidelinesp. 86

The specification of each northbound API utilizing the common API framework should define:
  1. the function of the API;
  2. the resource(s) involved;
  3. the list of supported operations and their usage;
  4. the list of input and output parameters along with applicable schemas, as required;
  5. the list of supported response codes;
  6. the behaviour of the network entity exposing the APIs (e.g. the CAPIF core function or the API exposing function) for each supported operation; and
  7. the list of applicable data types.
In order to facilitate the consistency of the northbound APIs utilizing the common API framework it is recommended to adopt the guidelines which define the following:
  1. consistent nomenclature for the operations, data structures and resources;
  2. design principles for the use of operations for common tasks; and
  3. a template for the consistent documentation of APIs.
The northbound APIs utilizing the common API framework should support the following properties:
  1. be extensible, such that it is possible to accommodate future requirements;
  2. support access control mechanisms;
  3. support charging, if applicable; and
  4. be backward and forward compatible with different versions of the same API.

9.3  Architecture design considerationsp. 87

Northbound APIs utilizing common API framework should adhere to RESTful architecture, whenever possible. Service operations can 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.
The API design:
  1. should have a uniform interface that conveys the resource model of the API to its client developers and:
    1. the implementation of the resource(s) involved in the APIs should be hidden from the client, but adequate operations should be designed to operate on the resource(s);
    2. any single API should be atomic;
    3. all resources involved in APIs should be accessible through a common approach, and similarly modified using a consistent approach;
  2. should allow the client (such as the API invoker) and the server (such as the CAPIF core function or the API exposing function) to evolve independently, i.e. the client should not have to be aware of the execution aspects of the APIs on the server;
  3. should be stateless such that each request from the client (such as the API invoker) to the server (such as the CAPIF core function or the API exposing function) contains all of the information necessary for the server to understand the request;
  4. should define the usage of standard operations, such as Create, Read, Update and Delete, consistently along with the applicable response codes;
  5. should allow to label responses as cacheable or non-cacheable, to improve network efficiency by supporting caching in the client (such as the API invoker);
  6. should prevent unwanted modification of the resources during invocation of APIs; and
  7. should support version control.

Up   Top   ToC