This is an excellent scenario to illustrate the different WSO2 API Manager

concepts! Let's imagine "WeatherCo" (the weather channel) wants to expose its
valuable weather data.

WeatherCo's API Management Journey with WSO2 APIM

Goal: WeatherCo wants to monetize its real-time weather data by offering APIs to
various weather apps (consumers) while ensuring performance, reliability, and
security.

1. API Creation and Publishing (WeatherCo's API Provider/Developer)

WeatherCo logs into the WSO2 API Publisher.

API Name: WeatherDataAPI

Context: /weather (The base URL for all weather API calls will be something like
https://api.weatherco.com/weather)

Version: 1.0.0

Description: "Provides real-time and historical weather data globally."

Resource Configuration (Defining What Data is Available):

This is where WeatherCo defines the specific "endpoints" or "paths" within its API
that expose different types of weather data.

Resource 1: Current Weather by City

Path: /current/{city}

Method: GET

Parameters: city (path parameter, e.g., /current/London), unit (query parameter,

e.g., ?unit=celsius)

Description: "Retrieves current weather conditions for a specified city."

Resource 2: 5-Day Forecast by Coordinates

Path: /forecast/5day

Method: GET

Parameters: latitude, longitude (query parameters)

Description: "Provides a 5-day weather forecast for specified geographical

coordinates."

Resource 3: Historical Data (Paid Access)

Path: /historical/{city}/{date}

Method: GET

Parameters: city, date

Description: "Accesses historical weather data for a city on a specific date."

(This might be a premium feature).
Endpoint Configuration (Where the Actual Data Lives):
This is crucial. WeatherCo has backend servers that actually process these requests
and fetch data from their databases or weather sensors.

Backend Services: Let's say WeatherCo has two main backend services for their
weather data:

WeatherServiceA running at https://backend-weather-data-a.weatherco.com

WeatherServiceB running at https://backend-weather-data-b.weatherco.com (This might

be a backup or a replica).

They also have a separate backend for historical data: https://backend-historical-

data.weatherco.com

Production Endpoints:

For /current/{city} and /forecast/5day (Real-time data):

WeatherCo configures a Failover Group endpoint here.

Primary URL: https://backend-weather-data-a.weatherco.com/api/v1/weather

Failover URL 1: https://backend-weather-data-b.weatherco.com/api/v1/weather

Explanation of Failover Group: If backend-weather-data-a becomes unresponsive or

returns specific error codes (e.g., 500, 503, connection timeouts), the WSO2
Gateway will automatically re-route the request to backend-weather-data-b. This
ensures high availability. Users will experience minimal or no downtime even if one
backend server fails. The Gateway intelligently switches to the next available
endpoint in the group.

For /historical/{city}/{date}:

Single HTTP Endpoint:

https://backend-historical-data.weatherco.com/archive/v1/weather
(Assuming historical data is less critical for immediate failover or has its own
high-availability setup).

Sandbox Endpoints:
WeatherCo wants app developers to test their integrations without hitting the live
production data. So, they set up sandbox environments for their backend services.

For /current/{city} and /forecast/5day (Sandbox):

Primary URL: https://sandbox-weather-data-a.weatherco.com/api/v1/weather

Failover URL 1: https://sandbox-weather-data-b.weatherco.com/api/v1/weather

(Again, a failover group, but pointing to non-production instances).

For /historical/{city}/{date} (Sandbox):

Single HTTP Endpoint:

https://sandbox-historical-data.weatherco.com/archive/v1/weather

Why Sandbox vs. Production Endpoints?

Sandbox:

Purpose: Testing, development, mocking, and simulating various scenarios (e.g.,

specific error codes, delays) without affecting live data or incurring real costs.

Data: Often uses synthetic, mocked, or non-production data.

Performance: Might have lower performance guarantees than production.

Usage: For app developers to build and test their apps before going live.

Production:

Purpose: Live, real-world usage by actual end-users.

Data: Real-time, live data.

Performance: Designed for high availability, low latency, and high throughput.

Usage: For fully developed and deployed weather apps.

Runtime Configuration (How Requests are Handled):

This defines policies and mediation sequences that apply to the API requests and
responses.

Authentication/Authorization: WeatherCo decides that all API calls require OAuth2

tokens. They configure the API to validate tokens with the WSO2 Key Manager. For
the /historical API, they might add a scope validation, ensuring only users with a
premium_data scope can access it.

Throttling:

For the CurrentWeather API, they might set a default tier of "100 requests per
minute" for free users.

For the Forecast API, a higher tier of "500 requests per minute".

For HistoricalData, a very strict tier, or even a pay-per-call model.

Caching: WeatherCo knows current weather data changes frequently but forecast data
might be static for a few minutes. They configure caching on the API Gateway for
/forecast/5day for a 5-minute duration to reduce load on the backend.

Message Transformations: Suppose their backend for current weather returns XML, but
they want to provide JSON to app developers. They can configure a "mediation
sequence" in WSO2 APIM to transform the XML response to JSON before sending it back
to the client.

Logging: Configure detailed logging for all incoming requests and outgoing
responses for debugging and auditing.

2. API Publishing and Deployment

WeatherCo changes the API lifecycle state from CREATED to PUBLISHED in the API
Publisher.

This action deploys the WeatherDataAPI configuration (including endpoints,

resources, and runtime policies) to the WSO2 API Gateway. Now the Gateway knows how
to handle requests for /weather/1.0.0/*.

3. API Discovery and Subscription (Weather App Developer)

Let's say "CloudView App" wants to integrate WeatherCo's data.

A CloudView developer goes to WeatherCo's Developer Portal.

They find the WeatherDataAPI (1.0.0). They can read the comprehensive documentation
(generated from the API definition).

They create a new "Application" in the Developer Portal, say "CloudView Mobile
App".

They subscribe their "CloudView Mobile App" to the WeatherDataAPI, choosing a

"Standard" subscription tier (which allows 100 requests/minute to the
CurrentWeather API, for example).

The Developer Portal provides them with API Keys or allows them to generate OAuth2
tokens for their application (using the Key Manager).

4. API TryOut (Developer Testing)

Before writing any code, the CloudView developer uses the "Try Out" feature in the
Developer Portal.

They enter London for the city parameter in the /current/{city} resource and hit
"Execute".

The Developer Portal (via the Gateway) makes a call to the Sandbox Endpoint of the
WeatherDataAPI.

The developer sees a sample JSON response, confirming the API's behavior. This
helps them quickly understand the API without consuming production resources.

5. API Invocation (CloudView App in Production)

The CloudView Mobile App is deployed to end-users.

When a user opens the app and requests weather for "Bengaluru":

The app sends an API request: GET

https://api.weatherco.com/weather/1.0.0/current/Bengaluru?unit=celsius

This request first hits the WSO2 API Gateway.

The Gateway Worker intercepts the request.

It validates the OAuth2 token (provided by the CloudView app) with the Key Manager.

It checks the CloudView app's subscription tier with the Traffic Manager and
ensures it hasn't exceeded its quota (e.g., 100 requests/minute). If it has, the
Gateway returns a 429 Too Many Requests error.

Since it's a production token, the Gateway uses the Production Endpoint for
/current/{city}.

It intelligently routes the request to the https://backend-weather-data-

a.weatherco.com/api/v1/weather/current/Bengaluru?unit=celsius.

If backend-weather-data-a is down, the Failover Group mechanism kicks in, and the
Gateway automatically tries
https://backend-weather-data-b.weatherco.com/api/v1/weather/current/Bengaluru?
unit=celsius.

The backend service processes the request and sends back the weather data (e.g., in
XML).

The Gateway applies the Runtime Configuration (mediation sequence) to transform the
XML to JSON.

The JSON response is sent back to the CloudView Mobile App.

All these steps are logged and usage statistics are sent to API Analytics.

6. Monitoring and Management

WeatherCo's operations team monitors the API Analytics dashboards.

They see that the WeatherDataAPI is receiving millions of requests daily.

They notice a few spikes in latency when backend-weather-data-a had a brief outage,
but thanks to the failover group, no API calls failed.

They identify that the HistoricalData API is generating significant revenue based
on the usage data.

Based on these insights, WeatherCo might:

Increase the capacity of their backend services or WSO2 Gateway workers.

Introduce new, higher-tiered subscription plans for the Forecast API.

Deprecate an old version of the API if no apps are using it anymore.

This comprehensive flow demonstrates how each component of WSO2 API Manager plays a
vital role in enabling WeatherCo to effectively manage, secure, and scale its
weather data APIs, while providing a smooth experience for app developers.