Unlocking the Power of APIs: A Beginner's Guide
In today's digital landscape, APIs (Application Programming Interfaces) play a vital role in facilitating seamless communication between different software systems. Essentially, APIs enable the exchange of data and functionality between these systems, allowing them to interact with each other effortlessly.
Application Programming Interface
Mastering API Management
To harness the full potential of APIs, effective management is crucial. This involves several key aspects, including:
- Creation: making the API accessible to other applications, enabling them to leverage its services.
- Documentation: providing clear guidelines on API usage, outlining expected request and response details for seamless interaction.
- Security: ensuring adherence to API usage policies to prevent security breaches and maintain data integrity.
- Monitoring: collecting and analyzing data on API usage and load to facilitate auditing, reporting, and optimization.
By mastering these aspects, you can unlock the full potential of your APIs and ensure a seamless user experience. For a step-by-step guide to success, visit t8tech.com.
The Role of API Gateways
An API Gateway acts as the entry point for APIs, enabling the enforcement of restrictions on incoming requests, management of API security, and implementation of configurable policies for logging, request headers, and data collection.
From here, API documentation can be published, and data can be analyzed to generate reports as needed.
API Gateway
RedHat 3-Scale API Management
RedHat 3-scale API Management provides a comprehensive API infrastructure, empowering users to share, secure, distribute, control, and monetize APIs on a high-performance platform designed for customer control and future growth. (Source: www.redhat.com)
Getting Started with API Onboarding
Before onboarding any API, it's essential to have the following prerequisites in place to ensure a smooth process:
- Openshift setup is completed.
- The 3scale API Management service is available on the same Openshift instance.
- The following API details are available:
- A working service URL.
- Methods (POST/GET).
- REST/SOAP specification.
- Request-response data for testing.
- Verification of access availability to the service from the environment.
- Application plans decisions (application plans should be decided at a global level, i.e., 3scale level).
By following these guidelines, you can ensure a seamless API onboarding experience and unlock the full potential of your APIs.
Illustrative Example in This Document
URL: http://10.2.3.4:80/app/apiname
METHOD: POST
Establishing API Gateway Staging and Production Routes
To facilitate seamless API management, we necessitate a few default API gateways, specifically tailored for staging and production environments.
These gateways essentially function as APICAST routes, enabling us to regulate traffic flow to your API hosted on a specific APICAST instance.
For a comprehensive understanding of APICAST, please refer to https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.3/html/deployment_options/apicast-overview.
Configuring a Backend
- Set up a backend.
- This backend represents the domain and port of the API, which can be shared by two or more products.
- This URL will be masked, and a 3scale URL will be provided post onboarding to access this API.
In this example, we are considering the base URL as: http://10.2.3.4:80/app.
Configuring a Product
A product is a precise path that specifies the exact API service we intend to onboard and monitor.
Once the product is created, you can navigate to integration -> settings to access the configuration details for deployment, authentication, and gateway responses.
The staging and production URLs indicate the service route names.
Note: The staging and production-base URLs can be configured only if the subdomain name remains unchanged.
Authentication Mechanisms
In 3scale, API authentication can be achieved through three distinct methods, outlined below:
- API Key (user_key) The application is identified and authenticated via a single string.
- App_ID and App_Key Pair The application is identified via the App_ID and authenticated via the App_Key.
- OpenID Connect Utilize OpenID Connect for any OAuth 2.0 flow.
We can gain a deeper understanding of the authentication mechanism from the following link: https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.1/html-single/api_authentication/index
Authentication Credentials Location
In this section, you can specify where to send the authentication credentials required for verification in the incoming request.
Configuring a Method
Each method in this API retrieves data on its individual usage, triggering the built-in Hits metric. Usage limits and pricing rules for individual methods are defined within each Application Plan.
Furthermore, a range of metrics can be tied to each method, and various analytics can be established. For example, data transfer metrics can be set up.
Navigate to PRODUCT -> Integration -> Method and metrics – > New Method.
To accurately count specific calls to your API, a method must be linked to one or more URL patterns in the Mapping Rules section of the integration page.
Configuring Metrics
Hits are built-in metrics that all methods report to. You can add additional top-level metrics here to track usage that shouldn’t increase the hit count. A metric is linked to one or more URL patterns in the Mapping Rules section of the integration page to accurately count specific metrics.
Navigate to PRODUCT -> Integration -> Method and metrics – > New Metrics.
Defining Mapping Rules
The mapping rules govern operations and can be linked to previously-defined methods/metrics. They can be mapped against the pre-defined hits metrics to increase the count on API hits.
Configuring an Application Plan for a Product
Application Plans establish the rules (limits, pricing, features) for using your API; every developer’s application accessing your API will operate within the constraints of an Application Plan. From a business perspective, Application Plans enable you to target different audiences by using multiple plans (i.e. ‘basic’, ‘pro’, ‘premium’) with different sets of rules.
The product configured requires an application plan mapped to it to manage the subscriptions of the accounts and their applications hitting the API.
Understanding the Distinction Between Method and Metrics
Method
Methods are specific to particular URLs. The increment of hits occurs for path matching methods by invoking the Service Management API of 3scale.
Metrics
We can measure any numerical value to be incremented for an API application by defining a custom metric. Any client (not just the API gateways) can increment a custom metric using the Service Management API.
This metric doesn’t necessarily require a URL; a simple string-based name will suffice.
API Deployment
Once all configuration is complete, we need to deploy the API to staging and production environments.
Navigate to Product -> Integration -> Configuration -> APIcast Configuration -> Promote to Staging. (Verify all configuration in this section before promoting it)
Upon successfully promoting the API from Staging to Production, the subsequent screen will display the endpoints made accessible by 3scale for interacting with these APIs.
API access points exposed by 3scale
Configuring Account Settings
The consumer of your API will be established as a distinct account.
For example, we have set up the following account:
Establishing a new account
A user is added during the account setup process, and additional users can be invited via email from the following screen.
Managing account settings
( Note: this requires SMTP setup to be completed in Openshift for the 3scale project)
User management can be accessed from the following screen:
User administration
The APIs available on 3scale will be made available to an account as applications.
The application setup is as follows, where we can observe a section labeled “API Credentials”; the provided key will be used to authenticate the account and allow the request to proceed.
Obtaining API credentials
Every application set up for an account is assigned a unique identifier.
The applications accessible to an account can be controlled via the subscriptions tab, as shown below, where an API management administrator can modify plan and subscription details.
(Important Note: If an account is tied to a default plan, it cannot be unsubscribed, as the API has designated that plan as the default configuration for all users)
API Gateway Hub
This centralized platform offers a user-friendly interface for API consumers to seamlessly onboard and subscribe to their preferred plan. The portal's layout can be tailored using CSS and JavaScript scripts to meet specific needs.
The REST API can publish comprehensive Swagger documentation on this portal, providing subscribers with instant access to detailed documentation that facilitates a deeper understanding of the API they are consuming.