ETSI TS 123 222 V15.2.0 (2018-07) TECHNICAL SPECIFICATION LTE; 5G; Common API Framework for 3GPP Northbound APIs (3GPP TS 23.222 version 15.2.0 Release 15) 3GPP TS 23.222 version 15.2.0 Release 15 1 ETSI TS 123 222 V15.2.0 (2018-07) Reference RTS/TSGS-0623222vf20 Keywords 5G,LTE ETSI 650 Route des Lucioles F-06921 Sophia Antipolis Cedex - FRANCE Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16 Siret N° 348 623 562 00017 - NAF 742 C Association à but non lucratif enregistrée à la Sous-Préfecture de Grasse (06) N° 7803/88 Important notice The present document can be downloaded from: http://www.etsi.org/standards-search The present document may be made available in electronic versions and/or in print. The content of any electronic and/or print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any existing or perceived difference in contents between such versions and/or in print, the only prevailing document is the print of the Portable Document Format (PDF) version kept on a specific network drive within ETSI Secretariat. Users of the present document should be aware that the document may be subject to revision or change of status. Information on the current status of this and other ETSI documents is available at https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx If you find errors in the present document, please send your comment to one of the following services: https://portal.etsi.org/People/CommiteeSupportStaff.aspx Copyright Notification No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm except as authorized by written permission of ETSI. The content of the PDF version shall not be modified without the written authorization of ETSI. The copyright and the foregoing restriction extend to reproduction in all media. © ETSI 2018. All rights reserved. DECTTM, PLUGTESTSTM, UMTSTM and the ETSI logo are trademarks of ETSI registered for the benefit of its Members. 3GPPTM and LTETM are trademarks of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners. oneM2M logo is protected for the benefit of its Members. GSM® and the GSM logo are trademarks registered and owned by the GSM Association. ETSI 3GPP TS 23.222 version 15.2.0 Release 15 2 ETSI TS 123 222 V15.2.0 (2018-07) Intellectual Property Rights Essential patents IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The information pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web server (https://ipr.etsi.org/). Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document. Trademarks The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners. ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks. Foreword This Technical Specification (TS) has been produced by ETSI 3rd Generation Partnership Project (3GPP). The present document may refer to technical specifications or reports using their 3GPP identities, UMTS identities or GSM identities. These should be interpreted as being references to the corresponding ETSI deliverables. The cross reference between GSM, UMTS, 3GPP and ETSI identities can be found under http://webapp.etsi.org/key/queryform.asp. Modal verbs terminology In the present document "shall", "shall not", "should", "should not", "may", "need not", "will", "will not", "can" and "cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of provisions). "must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation. ETSI 3GPP TS 23.222 version 15.2.0 Release 15 3 ETSI TS 123 222 V15.2.0 (2018-07) Contents Intellectual Property Rights ................................................................................................................................ 2 Foreword ............................................................................................................................................................. 2 Modal verbs terminology .................................................................................................................................... 2 Foreword ............................................................................................................................................................. 9 Introduction ........................................................................................................................................................ 9 1 Scope ...................................................................................................................................................... 10 2 References .............................................................................................................................................. 10 3 Definitions and abbreviations ................................................................................................................. 10 3.1 Definitions ........................................................................................................................................................ 10 3.2 Abbreviations ................................................................................................................................................... 11 4 Architectural requirements ..................................................................................................................... 12 4.1 General ............................................................................................................................................................. 12 4.1.1 Introduction................................................................................................................................................. 12 4.1.2 Requirements .............................................................................................................................................. 12 4.1.3 Requirements for supporting 3rd party API providers ................................................................................. 12 4.2 Service API publish and discover ..................................................................................................................... 12 4.2.1 Introduction................................................................................................................................................. 12 4.2.2 Requirements .............................................................................................................................................. 12 4.3 Security ............................................................................................................................................................ 12 4.3.1 Introduction................................................................................................................................................. 12 4.3.2 Requirements .............................................................................................................................................. 13 4.3.3 Additional requirements for 3rd party API provider .................................................................................... 13 4.4 Charging ........................................................................................................................................................... 13 4.4.1 Introduction................................................................................................................................................. 13 4.4.2 Requirements .............................................................................................................................................. 13 4.5 Operations, Administration and Maintenance .................................................................................................. 13 4.5.1 Introduction................................................................................................................................................. 13 4.5.2 Requirements .............................................................................................................................................. 14 4.6 Service API invocation monitoring .................................................................................................................. 14 4.6.1 Introduction................................................................................................................................................. 14 4.6.2 Requirements .............................................................................................................................................. 14 4.7 Logging ............................................................................................................................................................ 14 4.7.1 Introduction................................................................................................................................................. 14 4.7.2 Logging events related to service API invocations ..................................................................................... 14 4.7.3 Logging events related to API invoker onboarding .................................................................................... 14 4.7.4 Logging events related to API invoker interaction with the CAPIF ........................................................... 15 4.8 Auditing service API invocation ...................................................................................................................... 15 4.8.1 Introduction................................................................................................................................................. 15 4.8.2 Requirements .............................................................................................................................................. 15 4.9 Onboarding API invoker .................................................................................................................................. 15 4.9.1 Introduction................................................................................................................................................. 15 4.9.2 Requirements .............................................................................................................................................. 15 4.10 Policy configuration ......................................................................................................................................... 15 4.10.1 Introduction................................................................................................................................................. 15 4.10.2 Requirements .............................................................................................................................................. 15 4.11 Protocol design ................................................................................................................................................. 15 4.11.1 Introduction................................................................................................................................................. 15 4.11.2 Requirements .............................................................................................................................................. 15 5 Involved business relationships .............................................................................................................. 16 6 Functional model .................................................................................................................................... 16 6.1 General ............................................................................................................................................................. 16 6.2 Functional model description ........................................................................................................................... 16 ETSI 3GPP TS 23.222 version 15.2.0 Release 15 4 ETSI TS 123 222 V15.2.0 (2018-07) 6.3 Functional entities description .......................................................................................................................... 17 6.3.1 General ........................................................................................................................................................ 17 6.3.2 API invoker ................................................................................................................................................. 17 6.3.3 CAPIF core function ................................................................................................................................... 18 6.3.4 API exposing function ................................................................................................................................ 18 6.3.5 API publishing function .............................................................................................................................. 18 6.3.6 API management function .......................................................................................................................... 18 6.4 Reference points ............................................................................................................................................... 19 6.4.1 General ........................................................................................................................................................ 19 6.4.2 Reference point CAPIF-1 (between the API invoker and the CAPIF core function) ................................. 19 6.4.3 Reference point CAPIF-1e (between the API invoker and the CAPIF core function)................................ 19 6.4.4 Reference point CAPIF-2 (between the API invoker and the API exposing function) ............................... 19 6.4.5 Reference point CAPIF-2e (between the API invoker and the API exposing function) ............................. 20 6.4.6 Reference point CAPIF-3 (between the API exposing function and the CAPIF core function) ................. 20 6.4.7 Reference point CAPIF-4 (between the API publishing function and the CAPIF core function) .............. 20 6.4.8 Reference point CAPIF-5 (between the API management function and the CAPIF core function) ........... 20 7 Application of functional model to deployments ................................................................................... 21 7.1 General ............................................................................................................................................................. 21 7.2 Centralized deployment .................................................................................................................................... 21 7.3 Distributed deployment .................................................................................................................................... 21 8 Procedures and information flows .......................................................................................................... 24 8.1 Onboarding the API invoker to the CAPIF ...................................................................................................... 24 8.1.1 General ........................................................................................................................................................ 24 8.1.2 Information flows ....................................................................................................................................... 24 8.1.2.1 Onboard API invoker request ................................................................................................................ 24 8.1.2.2 Onboard API invoker response ............................................................................................................. 25 8.1.3 Procedure .................................................................................................................................................... 25 8.2 Offboarding the API invoker from the CAPIF ................................................................................................. 26 8.2.1 General ........................................................................................................................................................ 26 8.2.2 Information flows ....................................................................................................................................... 26 8.2.2.1 Offboard API invoker request ............................................................................................................... 26 8.2.2.2 Offboard API invoker response ............................................................................................................. 26 8.2.3 Procedure .................................................................................................................................................... 26 8.3 Publish service APIs ......................................................................................................................................... 27 8.3.1 General ........................................................................................................................................................ 27 8.3.2 Information flows ....................................................................................................................................... 27 8.3.2.1 Service API publish request .................................................................................................................. 27 8.3.2.2 Service API publish response ................................................................................................................ 28 8.3.3 Procedure .................................................................................................................................................... 28 8.4 Unpublish service APIs .................................................................................................................................... 28 8.4.1 General ........................................................................................................................................................ 28 8.4.2 Information flows ....................................................................................................................................... 29 8.4.2.1 Service API unpublish request .............................................................................................................. 29 8.4.2.2 Service API unpublish response ............................................................................................................ 29 8.4.3 Procedure .................................................................................................................................................... 29 8.5 Retrieve service APIs ....................................................................................................................................... 30 8.5.1 General ........................................................................................................................................................ 30 8.5.2 Information flows ....................................................................................................................................... 30 8.5.2.1 Service API get request ......................................................................................................................... 30 8.5.2.2 Service API get response ...................................................................................................................... 30 8.5.3 Procedure .................................................................................................................................................... 30 8.6 Update service APIs ......................................................................................................................................... 31 8.6.1 General ........................................................................................................................................................ 31 8.6.2 Information flows ....................................................................................................................................... 31 8.6.2.1 Service API update request ................................................................................................................... 31 8.6.2.2 Service API update response ................................................................................................................. 32 8.6.3 Procedure .................................................................................................................................................... 32 8.7 Discover service APIs ...................................................................................................................................... 32 8.7.1 General ........................................................................................................................................................ 32 8.7.2 Information flows ....................................................................................................................................... 33 ETSI 3GPP TS 23.222 version 15.2.0 Release 15 5 ETSI TS 123 222 V15.2.0 (2018-07) 8.7.2.1 Service API discover request ................................................................................................................ 33 8.7.2.2 Service API discover response .............................................................................................................. 33 8.7.3 Procedure .................................................................................................................................................... 33 8.8 Subscription, unsubscription and notifications for the CAPIF events .............................................................. 34 8.8.1 General ........................................................................................................................................................ 34 8.8.2 Information flows ....................................................................................................................................... 34 8.8.2.1 Event subscription request .................................................................................................................... 34 8.8.2.2 Event subscription response .................................................................................................................. 35 8.8.2.3 Event notification .................................................................................................................................. 35 8.8.2.4 Event notification acknowledgement .................................................................................................... 35 8.8.2.5 Event unsubscription request ................................................................................................................ 35 8.8.2.6 Event unsubscription response .............................................................................................................. 36 8.8.3 Procedure for CAPIF event subscription .................................................................................................... 36 8.8.4 Procedure for CAPIF event notifications .................................................................................................... 36 8.8.5 Procedure for CAPIF event unsubscription ................................................................................................ 37 8.8.6 List of CAPIF events .................................................................................................................................. 38 8.9 Revoking subscription of the CAPIF events .................................................................................................... 38 8.9.1 General ........................................................................................................................................................ 38 8.9.2 Information flows ....................................................................................................................................... 38 8.9.2.1 Subscription revoke notification ........................................................................................................... 38 8.9.2.2 Subscription revoke notification acknowledgement ............................................................................. 39 8.9.3 Procedure .................................................................................................................................................... 39 8.10 Authentication between the API invoker and the CAPIF core function ........................................................... 39 8.10.1 General ........................................................................................................................................................ 39 8.10.2 Information flows ....................................................................................................................................... 39 8.10.3 Procedure .................................................................................................................................................... 39 8.11 API invoker obtaining authorization to access service API ............................................................................. 40 8.11.1 General ........................................................................................................................................................ 40 8.11.2 Information flows ....................................................................................................................................... 40 8.11.3 Procedure .................................................................................................................................................... 40 8.12 AEF obtaining service API access control policy ............................................................................................ 41 8.12.1 General ........................................................................................................................................................ 41 8.12.2 Information flows ....................................................................................................................................... 41 8.12.2.1 Obtain access control policy request ..................................................................................................... 41 8.12.2.2 Obtain access control policy response................................................................................................... 41 8.12.3 Procedure .................................................................................................................................................... 42 8.13 Topology hiding ............................................................................................................................................... 42 8.13.1 General ........................................................................................................................................................ 42 8.13.2 Information flows ....................................................................................................................................... 43 8.13.2.1 Service API invocation request (API invoker – AEF-1) ....................................................................... 43 8.13.2.2 Service API invocation request (AEF-1 – AEF-2) ................................................................................ 43 8.13.2.3 Service API invocation response (AEF-2 – AEF-1) ............................................................................. 43 8.13.2.4 Service API invocation response (AEF-1 – API invoker) ..................................................................... 43 8.13.3 Procedure .................................................................................................................................................... 43 8.14 Authentication between the API invoker and the AEF prior to service API invocation .................................. 44 8.14.1 General ........................................................................................................................................................ 44 8.14.2 Information flows ....................................................................................................................................... 44 8.14.3 Procedure .................................................................................................................................................... 44 8.15 Authentication between the API invoker and the AEF upon the service API invocation ................................ 45 8.15.1 General ........................................................................................................................................................ 45 8.15.2 Information flows ....................................................................................................................................... 45 8.15.2.1 Service API invocation request with authentication information .......................................................... 45 8.15.2.2 Service API invocation response ........................................................................................................... 46 8.15.3 Procedure .................................................................................................................................................... 46 8.16 API invoker authorization to access service APIs ............................................................................................ 47 8.16.1 General ........................................................................................................................................................ 47 8.16.2 Information flows ....................................................................................................................................... 47 8.16.2.1 Service API invocation request ............................................................................................................. 47 8.16.2.2 Service API invocation response ........................................................................................................... 47 8.16.3 Procedure .................................................................................................................................................... 47 8.17 CAPIF access control ....................................................................................................................................... 48 8.17.1 General ........................................................................................................................................................ 48 ETSI 3GPP TS 23.222 version 15.2.0 Release 15 6 ETSI TS 123 222 V15.2.0 (2018-07) 8.17.2 Information flows ....................................................................................................................................... 49 8.17.2.1 Service API invocation request ............................................................................................................. 49 8.17.2.2 Service API invocation response ........................................................................................................... 49 8.17.3 Procedure .................................................................................................................................................... 49 8.18 CAPIF access control with cascaded AEFs ...................................................................................................... 50 8.18.1 General ........................................................................................................................................................ 50 8.18.2 Information flows ....................................................................................................................................... 50 8.18.2.1 Service API invocation request ............................................................................................................. 50 8.18.2.2 Service API invocation response ........................................................................................................... 50 8.18.3 Procedure .................................................................................................................................................... 51 8.19 Logging service API invocations ..................................................................................................................... 51 8.19.1 General ........................................................................................................................................................ 51 8.19.2 Information flows ....................................................................................................................................... 51 8.19.2.1 API invocation log request .................................................................................................................... 51 8.19.2.2 API invocation log response ................................................................................................................. 52 8.19.3 Procedure .................................................................................................................................................... 52 8.20 Charging the invocation of service APIs .......................................................................................................... 53 8.20.1 General ........................................................................................................................................................ 53 8.20.2 Information flows ....................................................................................................................................... 53 8.20.3 Procedure .................................................................................................................................................... 53 8.21 Monitoring service API invocation .................................................................................................................. 53 8.21.1 General ........................................................................................................................................................ 53 8.21.2 Information flows ....................................................................................................................................... 53 8.21.2.1 Monitoring service API event notification ............................................................................................ 53 8.21.2.2 Monitoring service API event notification acknowledgement .............................................................. 54 8.21.3 Procedure .................................................................................................................................................... 54 8.22 Auditing service API invocation ...................................................................................................................... 54 8.22.1 General ........................................................................................................................................................ 54 8.22.2 Information flows ....................................................................................................................................... 54 8.22.2.1 Query service API log request .............................................................................................................. 54 8.22.2.2 Query service API log response ............................................................................................................ 55 8.22.3 Procedure .................................................................................................................................................... 55 8.23 CAPIF revoking API invoker authorization ..................................................................................................... 56 8.23.1 General ........................................................................................................................................................ 56 8.23.2 Information flows ....................................................................................................................................... 56 8.23.2.1 Revoke API invoker authorization request ........................................................................................... 56 8.23.2.2 Revoke API invoker authorization response ......................................................................................... 56 8.23.2.3 Revoke API invoker authorization notify ............................................................................................. 56 8.23.3 Procedure for CAPIF revoking API invoker authorization initiated by AEF ............................................. 56 8.23.4 Procedure for CAPIF revoking API invoker authorization initiated by CAPIF core function ................... 57 9 API consistency guidelines .................................................................................................................... 58 9.1 General ............................................................................................................................................................. 58 9.2 Fundamental API Guidelines ........................................................................................................................... 58 9.3 Architecture design considerations ................................................................................................................... 59 10 CAPIF core function APIs ..................................................................................................................... 60 10.1 General ............................................................................................................................................................. 60 10.2 CAPIF_Discover_Service_API API ................................................................................................................ 60 10.2.1 General ........................................................................................................................................................ 60 10.2.2 Discover_Service_API operation ................................................................................................................ 60 10.2.3 Event_Subscription operation ..................................................................................................................... 61 10.2.4 Event_Notification operation ...................................................................................................................... 61 10.2.5 Event_Unsubscription operation ................................................................................................................. 61 10.3 CAPIF_Publish_Service_API API ................................................................................................................... 61 10.3.1 General ........................................................................................................................................................ 61 10.3.2 Publish_Service_API operation .................................................................................................................. 61 10.3.3 Unpublish_Service_API operation ............................................................................................................. 62 10.3.4 Update_Service_API operation .................................................................................................................. 62 10.3.5 Get_Service_API operation ........................................................................................................................ 62 10.3.6 Event_Subscription operation ..................................................................................................................... 62 10.3.7 Event_Notification operation ...................................................................................................................... 62 ETSI 3GPP TS 23.222 version 15.2.0 Release 15 7 ETSI TS 123 222 V15.2.0 (2018-07) 10.3.8 Event_Unsubscription operation ................................................................................................................. 63 10.4 CAPIF_Events API .......................................................................................................................................... 63 10.4.1 General ........................................................................................................................................................ 63 10.4.2 Event_Subscription operation ..................................................................................................................... 63 10.4.3 Event_Notification operation ...................................................................................................................... 64 10.4.4 Event_Unsubscription operation ................................................................................................................. 64 10.5 CAPIF_API_invoker_management API .......................................................................................................... 64 10.5.1 General ........................................................................................................................................................ 64 10.5.2 Onboard_API_Invoker operation ................................................................................................................ 64 10.5.3 Offboard_API_Invoker operation ............................................................................................................... 64 10.5.4 Event_Subscription operation ..................................................................................................................... 65 10.5.5 Event_Notification operation ...................................................................................................................... 65 10.5.6 Event_Unsubscription operation ................................................................................................................. 65 10.6 CAPIF_Authentication_Authorization API ..................................................................................................... 65 10.6.1 General ........................................................................................................................................................ 65 10.6.2 Authenticate operation ................................................................................................................................ 65 10.6.3 Obtain_Authorization operation ................................................................................................................. 66 10.7 CAPIF_Monitoring API ................................................................................................................................... 66 10.7.1 General ........................................................................................................................................................ 66 10.7.2 Event_Subscription operation ..................................................................................................................... 66 10.7.3 Monitoring_Service_API_Notification operation ....................................................................................... 66 10.7.4 Event_Unsubscription operation ................................................................................................................. 66 10.8 CAPIF_Logging_API_Invocation API ............................................................................................................ 67 10.8.1 General ........................................................................................................................................................ 67 10.8.2 Log_API_Invocation operation .................................................................................................................. 67 10.9 CAPIF_Auditing API ....................................................................................................................................... 67 10.9.1 General ........................................................................................................................................................ 67 10.9.2 Query_ API_Invocation_Log operation...................................................................................................... 67 Annex A (informative): Overview of CAPIF operations..................................................................... 68 Annex B (informative): CAPIF relationship with network exposure aspects of 3GPP systems .... 70 B.0 CAPIF utilization by service API provider ............................................................................................ 70 B.1 CAPIF relationship with 3GPP EPS network exposure ......................................................................... 71 B.1.1 General ............................................................................................................................................................. 71 B.1.2 Deployment models .......................................................................................................................................... 71 B.1.2.1 General ........................................................................................................................................................ 71 B.1.2.2 SCEF implements the CAPIF architecture ................................................................................................. 71 B.1.2.3 SCEF implements the service specific aspect compliant with the CAPIF architecture .............................. 72 B.1.2.4 Distributed deployment of the SCEF compliant with the CAPIF architecture ........................................... 73 B.2 CAPIF relationship with 3GPP 5GS network exposure ......................................................................... 74 B.2.1 General ............................................................................................................................................................. 74 B.2.2 Deployment models .......................................................................................................................................... 75 B.2.2.1 General ........................................................................................................................................................ 75 B.2.2.2 NEF implements the CAPIF architecture ................................................................................................... 75 B.2.2.3 NEF implements the service specific aspect compliant with the CAPIF architecture ................................ 76 B.2.2.4 Distributed deployment of the NEF compliant with the CAPIF architecture ............................................. 77 Annex C (informative): CAPIF role in charging ................................................................................. 79 C.1 General ................................................................................................................................................... 79 C.2 CAPIF role in online charging ............................................................................................................... 79 C.3 CAPIF role in offline charging ............................................................................................................... 80 Annex D (informative): CAPIF relationship with external API frameworks ................................... 81 Annex E (normative): Configuration data for CAPIF ..................................................................... 82 Annex F (informative): Change history ............................................................................................... 83 ETSI 3GPP TS 23.222 version 15.2.0 Release 15 8 ETSI TS 123 222 V15.2.0 (2018-07) History .............................................................................................................................................................. 84 ETSI 3GPP TS 23.222 version 15.2.0 Release 15 9 ETSI TS 123 222 V15.2.0 (2018-07) Foreword This Technical Specification has been produced by the 3rd Generation Partnership Project (3GPP). The contents of the present document are subject to continuing work within the TSG and may change following formal TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an identifying change of release date and an increase in version number as follows: Version x.y.z where: x the first digit: 1 presented to TSG for information; 2 presented to TSG for approval; 3 or greater indicates TSG approved document under change control. y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, updates, etc. z the third digit is incremented when editorial only changes have been incorporated in the document. Introduction In 3GPP, there are multiple northbound API-related specifications (e.g. APIs for Service Capability Exposure Function (SCEF) functionalities defined in 3GPP TS 23.682 [2], API for the interface between MBMS service provider and BM- SC defined in 3GPP TR 26.981 [5]). To avoid duplication and inconsistency of approach between different API specifications, 3GPP has considered the development of a common API framework (CAPIF) that includes common aspects applicable to any northbound service APIs. The present document specifies the functional model, procedures and information flows needed to support the CAPIF, and the guidelines for consistent northbound API (service and CAPIF APIs) development in 3GPP. NOTE: It is possible to use the CAPIF defined common aspects for other APIs as well, apart from northbound APIs. ETSI