...
Please note the comparison of API GW and existing ONAP projects like Ext-API and MSB below. The comparison also covers what additional capability API GW bring in to augment the existing functionality. As for this proposal, the directions provided by Architecture committee and TSC will be followed once the need for such functionality is agreed with all stakeholders.
Architecture
API GW consists of four main building blocks – Gateway, API GW Management Component, API GW Configuration store, API GW UI. Gateway function is a stateless reverse proxy which can be instantiated on demand, scaled and distributed. It hosts a set of plugins that enhance the API control logic. The plugins are developed using the gateway SDK and attached as a library during the initialization. Gateway and Plugins refers the API configuration (i.e information about the on boarded API) from Configuration and Analytics data store. The Configuration & Analytics DS persists the API configuration and API transactional metrics. API GW can work with an inbuilt Auth provider capable of centrally managing the Authentication, Authorization of the exposed APIs. The API GW UI hosts the Management, Design and Monitoring UIs. The GW function maintains statistics and log information of APIs and stores the information in the Configuration and Analytics store. It is also possible to integrate the Configuration and Analytics Store with external monitoring solutions like Prometheus or alert engines to notify external consumers about API statistics.
Scope
Following are the proposed capabilities
- API LCM: Manage the lifecycle of API – Onboarding of APIs as swagger or equivalent templates, Design of APIs with context path and backend endpoints, Association of API with required plugins to control runtime behavior, Activation or Deactivation of API, Management of Security aspects of the API
- API Market Place, API Catalog Management: Provide a consumer-friendly and developer friendly API Management interface
- Plan, Subscription Management: Ability to design API plans with different levels of control and provide management interface to subscribe to a particular API and approve the specific subscription.
- Content/Payload based API routing: Currently MSB in ONAP Supports API routing based on Service endpoints, but not strictly based on the API payload or API headers. This is an augmented capability on top of MSB to be consumed by use case teams and projects so that any custom routing can be incorporated at the API layer rather than at the individual project level.
- API Federation: Currently there is no consistent mechanism for federation between two ONAP instances at least at the API layer. This capability allows projects to leverage API GW as a gateway that manages communication between multiple instances of ONAP. Note that this capability only covers the
- Consistent Security Management: Manage API security– primarily transactional security – Authentication, Authorization, Encryption. Authentication and Authorization is planned to be based on a pluggable model, i.e capability to integrate with the Auth Provider IDP within the operator premise or reuse capabilities provided by AAF. Encryptions is enabled through HTTPS based secure channel – for this API GW maintains a keystore and truststore (PKCS12 based stores) with certificates signed by an authorized signing authority. API GW supports Authorization/Authentication based on OAuth 2.0, Open ID Connect, SCIM 2.0, etc.
- Circuit Breaking, Timeout, Retries, and Rate Control: Capability to control the API consumption by tuning the APIs usage properties. These capabilities may be controlled on demand using the management APIs exposed by API GW.
- Flexible Request and Response Transformation: Capability to transform the API payload (request or response) based on predefined transformation logic – The transformation logic can be implemented as plugin and can be configured at runtime using exposed properties. The transformation plugin may also support expression languages (such as JOLT) or script insertion to transform the request or response. Other transformation capabilities include header, URL transformation, XML/JSON payload transformation, Request Method transformation, Security mechanism transformation etc.
- API Sharding (Targeted API Deployment) : Targeted deployment of APIs at distributed API GW Instances based on specific criteria – i.e geographic proximity, load etc.
- Service Discovery: Discover the API endpoints (backend Service APIs) based on registry look up and load balance the request across discovered services.
- Façade: Aggregate/Compose complex low-level APIs and expose simplified façade APIs associated with service endpoints
- API Policy Enforcement: Define API control policies – security or run time behavior
- Common look and feel and documentation: Ensure common look and feel, documentation for exposed ONAP APIs
- API Metrics Collection, Analytics, Metering, Audit, Logging: Capability track all the API transactions and identify the usage pattern, traffic
- Alerts: Enable API consumption specific alerts so that corrective actions can be carried out on-demand.
- White Listing, Black Listing of APIs based on the Subscription profile, Policy
- API Designer: a Designer tool to import swagger APIs, attach appropriate policies associated with API, commission and decommission APIs, manage subscriptions and plans
Short Term Capabilities (Proof of concept and first release after completing PoC):
- Capability marked in Blue (To be prioritized)
Long Term Capabilities:
- Rest of the capabilities not covered in Short Term
Architecture Alignment
Potential placement of API GW in ONAP Architecture
Option 1: Co-exist with Ext-API , but may support external and internal APIs on need basis
Option 2: Co-exist with MSB, but handles gateway functionality independently. MSB handles the Registry and Service Discovery.
Option 3: API GW exists as an independent functional component
API GW and External API:
- Exiting Capabilities in Ext-API :
- Mediation/Adaptation between TMF APIs and ONAP internal APIs
- Leverages JOLT JSON Transformation Templates for Payload transformation
- Order State Monitoring – Hub Resources Management for callbacks
- Repository for Service Specification Catalog , Service Order Mapping details
- Leverages SDC JTOSCA Parser for TOSCA Parsing
- Static transformation logic and routing implemented in code
- Capabilities Augmented by API GW Solution
- Management toolsets for configuring API context and endpoint
- API Analytics
- Full API Lifecycle Management – Onboard, Policy Control, retire, WL,BL
- API Subscription/Plan management
- API Policy management
- Enhanced API Security Management – OAuth2, JWT,
Open ID, SCIM 2.0 – All inbuilt and centrally managed - Script insertion in API execution flow
- Configurable APIs, Transformation logic than static Code
- Pre-built API Processing plugins
- API Aggregation and Composition
- Swagger Import and Plugin chaining
- Management and Monitoring UI
API GW and MSB:
How API GW Solution solves the problems started?
- Different API Management Approaches: Logically Centralized API GW component enables consistent approach for managing APIs without the need to develop redundant API Adaptor, hiding a variety of approaches followed by different ONAP components
- Standard Alignment: API GW support rich transformation capability with inbuilt plugins and support for expression language that can be configured on demand rather than developing from scratch ( and subsequently waiting for a long release cycle.)
- Production deployments might require interoperability with legacy and 3rd Party components: This is an inherent capability of API GW. API GW allows flexible integration with external and internal systems with toolsets for HTTP Method conversion, HTTP Payload Conversion, REST/SOAP transformation, JSON/XML transformation, JSON to JSON transformation, Different types of security mechanisms, etc. API GW can expose Façade APIs which compose the internal functionality of ONAP at desired levels of complexity.
- Evolution of Platform functional capability vs. Use Case capability: Helps in creating abstraction layer or Façade as needed for different use cases, allowing the projects to evolve independently
Architecture
API GW consists of four main building blocks – Gateway, API GW Management Component, API GW Configuration store, API GW UI. Gateway function is a stateless reverse proxy which can be instantiated on demand, scaled and distributed. It hosts a set of plugins that enhance the API control logic. The plugins are developed using the gateway SDK and attached as a library during the initialization. Gateway and Plugins refers the API configuration (i.e information about the on boarded API) from Configuration and Analytics data store. The Configuration & Analytics DS persists the API configuration and API transactional metrics. API GW can work with an inbuilt Auth provider capable of centrally managing the Authentication, Authorization of the exposed APIs. The API GW UI hosts the Management, Design and Monitoring UIs. The GW function maintains statistics and log information of APIs and stores the information in the Configuration and Analytics store. It is also possible to integrate the Configuration and Analytics Store with external monitoring solutions like Prometheus or alert engines to notify external consumers about API statistics.
Scope
Following are the proposed capabilities
- API LCM: Manage the lifecycle of API – Onboarding of APIs as swagger or equivalent templates, Design of APIs with context path and backend endpoints, Association of API with required plugins to control runtime behavior, Activation or Deactivation of API, Management of Security aspects of the API
- API Market Place, API Catalog Management: Provide a consumer-friendly and developer friendly API Management interface
- Plan, Subscription Management: Ability to design API plans with different levels of control and provide management interface to subscribe to a particular API and approve the specific subscription.
- Content/Payload based API routing: Currently MSB in ONAP Supports API routing based on Service endpoints, but not strictly based on the API payload or API headers. This is an augmented capability on top of MSB to be consumed by use case teams and projects so that any custom routing can be incorporated at the API layer rather than at the individual project level.
- API Federation: Currently there is no consistent mechanism for federation between two ONAP instances at least at the API layer. This capability allows projects to leverage API GW as a gateway that manages communication between multiple instances of ONAP. Note that this capability only covers the
- Consistent Security Management: Manage API security– primarily transactional security – Authentication, Authorization, Encryption. Authentication and Authorization is planned to be based on a pluggable model, i.e capability to integrate with the Auth Provider IDP within the operator premise or reuse capabilities provided by AAF. Encryptions is enabled through HTTPS based secure channel – for this API GW maintains a keystore and truststore (PKCS12 based stores) with certificates signed by an authorized signing authority. API GW supports Authorization/Authentication based on OAuth 2.0, Open ID Connect, SCIM 2.0, etc.
- Circuit Breaking, Timeout, Retries, and Rate Control: Capability to control the API consumption by tuning the APIs usage properties. These capabilities may be controlled on demand using the management APIs exposed by API GW.
- Flexible Request and Response Transformation: Capability to transform the API payload (request or response) based on predefined transformation logic – The transformation logic can be implemented as plugin and can be configured at runtime using exposed properties. The transformation plugin may also support expression languages (such as JOLT) or script insertion to transform the request or response. Other transformation capabilities include header, URL transformation, XML/JSON payload transformation, Request Method transformation, Security mechanism transformation etc.
- API Sharding (Targeted API Deployment) : Targeted deployment of APIs at distributed API GW Instances based on specific criteria – i.e geographic proximity, load etc.
- Service Discovery: Discover the API endpoints (backend Service APIs) based on registry look up and load balance the request across discovered services.
- Façade: Aggregate/Compose complex low-level APIs and expose simplified façade APIs associated with service endpoints
- API Policy Enforcement: Define API control policies – security or run time behavior
- Common look and feel and documentation: Ensure common look and feel, documentation for exposed ONAP APIs
- API Metrics Collection, Analytics, Metering, Audit, Logging: Capability track all the API transactions and identify the usage pattern, traffic
- Alerts: Enable API consumption specific alerts so that corrective actions can be carried out on-demand.
- White Listing, Black Listing of APIs based on the Subscription profile, Policy
- API Designer: a Designer tool to import swagger APIs, attach appropriate policies associated with API, commission and decommission APIs, manage subscriptions and plans
Short Term Capabilities (Proof of concept and first release after completing PoC):
- Capability marked in Blue (To be prioritized)
Long Term Capabilities:
- Rest of the capabilities not covered in Short Term
Architecture Alignment
Potential placement of API GW in ONAP Architecture
Option 1: Co-exist with Ext-API , but may support external and internal APIs on need basis
Option 2: Co-exist with MSB, but handles gateway functionality independently. MSB handles the Registry and Service Discovery.
Option 3: API GW exists as an independent functional component
API GW and External API:
- Exiting Capabilities in Ext-API :
- Mediation/Adaptation between TMF APIs and ONAP internal APIs
- Leverages JOLT JSON Transformation Templates for Payload transformation
- Order State Monitoring – Hub Resources Management for callbacks
- Repository for Service Specification Catalog , Service Order Mapping details
- Leverages SDC JTOSCA Parser for TOSCA Parsing
- Static transformation logic and routing implemented in code
- Capabilities Augmented by API GW Solution
- Management toolsets for configuring API context and endpoint
- API Analytics
- Full API Lifecycle Management – Onboard, Policy Control, retire, WL,BL
- API Subscription/Plan management
- API Policy management
- Enhanced API
- Existing Capabilities in MSB
- API Endpoint Registration and Discovery
- Static API Endpoint Routing based on port and Service URL (No payload-based routing)
- API Load balancing
- Service Mesh Integration Prototype
- Integration with AAF for security policy enforcement (?)
- Integration with OOM for dynamic Service Registration
- Management APIs for registration of Services
- Capabilities Augmented by API GW Solution
- Full API Lifecycle Management
- Manual and Bulk API Import – Swagger or Management API
- API Subscription/Plan management, API Discovery
- API Catalog and Marketplace
- Integration with multiple external IDP, Monitoring solution
- Rate Limit, Quota Mgmt , Circuit Break
- Tenant, Role Management
- Whitelisting , Black Listing
- Enhanced API Security Management – OAuth2, JWT,
Open ID etc, SCIM 2.0 – All inbuilt and centrally managed - Script insertion in the API execution flow
- Configurable APIs, Transformation logic
- API Aggregation and Composition Management and Monitoring UI
- and centrally managed
- Script insertion in API execution flow
- Configurable APIs, Transformation logic than static Code
- Pre-built API Processing plugins
- API Aggregation and Composition
- Swagger Import and Plugin chaining
- Management and Monitoring UI
API GW and MSB:
- Existing Capabilities in MSB
- API Endpoint Registration and Discovery
- Static API Endpoint Routing based on port and Service URL (No payload-based routing)
- API Load balancing
- Service Mesh Integration Prototype
- Integration with AAF for security policy enforcement (?)
- Integration with OOM for dynamic Service Registration
- Management APIs for registration of Services
- Capabilities Augmented by API GW Solution
- Full API Lifecycle Management
- Manual and Bulk API Import – Swagger or Management API
- API Subscription/Plan management, API Discovery
- API Catalog and Marketplace
- Integration with multiple external IDP, Monitoring solution
- Rate Limit, Quota Mgmt , Circuit Break
- Tenant, Role Management
- Whitelisting , Black Listing
- Enhanced API Security Management – OAuth2, JWT,
Open ID etc. – All inbuilt and centrally managed - Script insertion in the API execution flow
- Configurable APIs, Transformation logic
- API Aggregation and Composition
- Management and Monitoring UI
Benefits for ONAP
Support a single source of truth for High level APIs, rather than each project maintaining own versions
- Augments MSB and Ext-API capabilities
Facade layer: Enables development of a Facade layer which abstracts the complexities of internal API
Request/Response Transformation: Enables ONAP components to align with SDO APIs more easily without changing the existing capabilities
Low impact on existing projects: Enable Operators to plugin standard and legacy integration API adaptors without impacting the ONAP components
Allows Projects/Components to focus on core functionality rather than worrying about API Transformation
Enables Tenancy/RBAC Management: Centralized API management can help in the implementation of tenancy management through policies.
- How does this project fit into the rest of the ONAP Architecture?
API Gateway provides an API and UI interface. API can be used by components in ONAP or by administrative users to manage the lifecycle of high-level APIs. UI is primarily intended for an administrator to provision and manage APIs. The UI is also suitable for the end user as the API GW provides a consumer view – API Marketplace which can be used to subscribe to specific APIs. - What other ONAP projects does this project depend on?
OOM for deployment, MSB or Specific ONAP components whose APIs need to be abstracted behind a façade API (standard API), AAF for Security – Authorization, Authentication and Certificate Management - In Relation to Other ONAP Components
...