Introduction

Torry Harris API Manager™ also known as THAPIM™ is an integrated platform for developing, integrating and exposing managed APIs in cloud, on-premise and hybrid architectures to support your digital transformation strategy. It enables API developers to design, publish and manage the lifecycle of APIs, while API product managers can create API products from one or more APIs.

Architectural Overview

The image below provides a high-level Architectural overview of Torry Harris API Manager™ and its components.

Benefits of Torry Harris API Manager™

The Torry Harris API Manager application offers comprehensive features and benefits designed to simplify API management, improve security, drive monetization strategies, enable integration and customization based on specific business requirements.

1. Advanced API Management Capabilities: It has extensive API management tools such as secure API proxies, the ability to create API Packs from several APIs and support for JavaScript transformation rules.

2. Monetization Features: The application allows users to attach price plans, specify free, paid quotas, collect setup and termination costs as needed.

3. Effective Policy Enforcement: The application supports OAuth 2.0, request throttling, rate limiting, time-based restriction, protection against XML, JSON threats and ensuring comprehensive policy enforcement to improve security and control.

4. Multi-Tenancy Support: Built-in multi-tenancy allows each business unit to offer its APIs, customize the developer portal, manage setup and termination fees as needed. It also enables publisher-driven developer onboarding.

5. Granular Control and Delegated Administration: The application provides fine-grained control over publisher user functions for individuals and groups, as well as delegated administrative features, which improves flexibility and governance.

6. Streamlined Workflows: Approval cycles for typical API publishing tasks, separation of concerns between business, technical users and optional approval of developer registrations all help to optimize workflows and ensure effective API management processes.

7. Integration Flexibility: Integration points provide easy integration of identity management and billing systems, while the extension of built-in monetization rules improves responsiveness to a wide range of business requirements.

8. Customization Options: Every feature in the Publisher and Developer Portal is an API, which allows for significant customization based on unique requirements. Furthermore, there are no dependence on third-party content management systems, which increases simplicity and flexibility.

9. Comprehensive Analytics: Built-in analytics enable publisher user to effectively track API usage, with dashboards and charts available through the publisher portal. Users can use data to create customized reports, allowing them to make better choices.

Core Components of Torry Harris API Manager™

The Core components of Torry Harris API Manager™ are:

1. Publisher Portal
2. Developer Portal
3. Gateway

Publisher Portal

The Publisher portal provides a safe and scalable platform to publish, promote and monitor Application Programming Interfaces (APIs).

The Publisher Portal includes the following features:

Advanced API Management

• Create Secure API proxies.
• Create API packs from multiple APIs.
• Create transformation rules using JavaScript. 
• Import and generate Swagger 2.0 and 3.0 specifications.
• Supports REST to/from SOAP conversion.
• Supports GraphQL API.

Monetization

• Attach pricing plans. 
• Set free and paid quotas. 
• Optionally collect setup and termination fees. 
• Create a rate card for the store.

Policy Enforcement

• Features include OAuth 2.0 authentication, request throttling, rate limiting and time of day limitations.
• XML and JSON threat protection.
• Back-end overload protection.
• Cluster-wide global policies.

Multiple Publishing Teams

• Multi-tenancy allows business units to offer their own APIs. 
• Tenants can customize the developer portal. 
• Setup and termination fees can be collected. 
• Publisher-driven developer onboarding is optional.

Granular Control.

• Fine-grained control over publisher user functions for both individuals and groups.
• Delegated administration.

Workflows

• Approval cycles for common API publishing tasks. 
• Separation of concerns for Business and Technical users.
• Pricing definition and change approval.
• Policy approval.
• Approval of developer registrations is optional.

Identity Management Integration

• Integration points for quickly connecting your identity management.
• Map your enterprise directory to the publisher users and groups.

Billing integration

• Integration points for quickly connecting your charging system.
• Extension of built-in monetization rules.

Customization

• Each function in the Publisher and Developer portal is an API.

Analytics

• Analytics for publisher user to track API usage. 
• Publisher portal dashboards and charts. 
• Customizable data reporting.

Content Management for the Developer Portal

• Tenant-level customization. 
• Integrate your content management in needed.

Developer Portal

The Developer Portal is a web-based platform for app developers. This portal helps users discover, test and integrate APIs into their applications.

The Developer Portal includes the following features:

Self service

• Self-registration for developers and delegated administration.
• Application registration.

Subscription management

• Request for API Plan Subscription - Renewal of Subscription.

Workflows

• Approvals for production usage.

Key management

• Self-service-based Token generation and API-driven life cycle management.
• Subscription key, Ip White listing , Header and Query parameter management.

Integrated Discussion Forum

• Forum for discussion between publisher user and consumers. 
• Submit feature requests. 
• Track bugs.

Analytics

• Integrated analytics to track API usage.
• Revenue share reporting.

Gateway

The Gateway acts as the entry point for all API requests. It serves as a bridge between clients (such as mobile apps, web applications, or other services) and the backend services that host the APIs.

The Gateway includes the following features:

• Event driven HTTP request processing
• High concurrency
• JavaScript engine for high-speed header and payload transformation
• OAuth 2.0
• HTTP Basic
• API-driven and Publisher portal-driven administration
• Asynchronous statistics and log recording
• XML and JSON threat protection
• Rate limiting and throttling policy enforcement
• Back-end Protection
• WS security
• Maximum Concurrent Transactions
• Data recording and masking
• Microgateway

Key Concept

If you are new to the world of APIs, this section will help you understand the concepts and words you may encounter when working as an API Publisher user/Consumer.

Publisher Portal

The Publisher Portal is a secure, scalable web platform for publishing, promoting, and monitoring APIs.

It offers tools to:

• Define, design, and publish APIs
• Manage API versions and lifecycle
• Promote APIs to the developer community
• Enforce runtime policies
• Analyze API usage and statistics
• Customize and brand the Developer Portal to drive API consumption

API

An API (Application Programming Interface) provides a set of resources or operations that allow developers to access and use web services through endpoints. It enables applications to interact with and reuse data and functionality from other systems.

There are three main types of Web APIs:

• SOAP APIs
• REST APIs
• GraphQL APIs

SOAP API

SOAP is a protocol that defines how to structure messages, operations, and web service locations using XML and WSDL schemas. It exposes operations, such as changeEmployeeName(EmployeeID, oldEmployeeName, newEmployeeName), and uses these to perform tasks.

SOAP APIs are stateful, preserving session states across interactions, and provide formal contracts for API interfaces. They are particularly suited for high-reliability applications, such as banking systems, where transaction integrity and formal agreements are crucial.

REST API

REST is an architectural style that operates over standard HTTP and uses URIs to access resources via CRUD methods (GET, PUT, DELETE, POST). For example, to update an employee's name, you might use a URI like http://sample.test/api/employee/22 and perform a PUT request with the new employee name in the body. A GET request to this URI would confirm the update with an HTTP status code 200. REST is stateless, meaning it does not retain service state between requests, and supports various data formats, including JSON, XML, and YAML.

REST simplifies integration and development by leveraging HTTP and CRUD operations. It is ideal for mobile and web applications due to its scalability and lightweight nature.

GraphQL API

GraphQL is a query language for APIs that allows fetching specific data in a single call, making it faster and more flexible. It supports only GET for data retrieval and POST for modifications.

Resources can be added to a GraphQL API using either GraphQL Schema Definition Language (uploading .graphql or .graphqls files) or Introspection Query Result (uploading .json files). These files contain the necessary information for invoking GraphQL methods, which are parsed by the TH API Manager to populate API Resources.

Proxy Endpoint and Real Endpoint

Endpoints are server-side URLs that allow client-side devices to access a web service. They typically use an HTTP URL format, such as http://myapi.com/someservice/, and can handle multiple requests and responses. An endpoint serves as a reference point for sending and receiving information, with each URL potentially pointing to different resources or operations. For example, a REST API might have endpoints like http://apis.com/mobiles/1234 or http://apis.com/mobiles/1235 to access specific mobile IDs.

Proxy Endpoint

A Proxy Endpoint hides the back-end system from direct access, exposing only necessary parts of the application. It is configured with a URL that clients use to indirectly access back-end services. Proxy Endpoints also manage security policies, usage limits, and access control.

Real Endpoint

A Real Endpoint is the target endpoint that directs requests to back-end services. End-users and developers interact with Proxy Endpoints, not Real Endpoints. In TH API Manager, a Real Endpoint is represented as http://<IP or hostname>:<port>/<path>.

API Pack

API Packs are the way APIs are organized and presented to developers. An API Pack is a bundled set of resources and operations from various APIs, including their allowed methods. Once prepared for use, Packs are listed in the API Store within the Developer portal. Developers can browse available Packs in the Store and subscribe to a Pack Plan to access the APIs.

API Monetization - Usage Plans

A Usage Plan is a subscription-based configuration that outlines pricing details, including free and paid tiers, monthly fees, and sign-up costs. These plans are based on API resources within a Pack and are governed by security and usage policies.

Monetization Strategies

• Usage-based Pricing: Charges based on the number of API calls within a set period. Multiple Usage Plans can be created.
• Revenue Sharing-based Pricing: Pricing is based on API-generated revenue, with a portion shared with the Developer. Only one Usage Plan can be used.
• Transaction-based Pricing: Pricing is a percentage of the transaction value, configurable by the Publisher. Only one Usage Plan can be used.
• Non-Monetized: No subscription or one-time fees; can have limited or unlimited request terms. Multiple Usage Plans can be created.

Each Pack supports only one Monetization Strategy across all its Plans. For example, if a Pack uses Usage-based Pricing, it cannot include Revenue-sharing, Transaction-based, or Non-monetized Plans.

TH API Manager supports multiple plans for Usage-based and Non-monetized strategies, but only one plan for Revenue-sharing and Transaction-based strategies.

Gateway

An API Gateway is a networking component that manages various functions such as transformations, rate limiting, throttling, data recording, and logging for analytics. It controls traffic and enforces security for APIs.

The Gateway acts as a proxy, separating back-end systems from consumer-facing APIs. This allows API developers to enhance interfaces without affecting back-end systems and protects back-end systems from direct exposure. Key functions of the API Gateway include:

• Data Routing: Directs API requests to target endpoints.
• Security: Protects back-end systems from attacks and provides a secure API access platform.
• Authentication and Authorization: Verifies credentials using Basic Authentication and OAuth methods.
• Traffic Control: Manages API traffic with rate limiting and throttling.
• Data Transformation: Converts back-end data into app-friendly formats.
• Performance: Enhances efficiency and minimizes downtime.
• Data Logging: Records events for analysis, reporting, and auditing.

TH API Manager leverages the API Gateway for comprehensive policy management and enforcement while ensuring robust API security.

The API Gateway secures APIs at two levels:

• Message-Level Security: Ensures end-to-end protection of messages, maintaining confidentiality and integrity from sender to recipient. TH API Manager supports this through Basic Authentication, OAuth 2.0, and WS Security (for SOAP).

• Transport-Level Security: Provides point-to-point encryption for data transmission between server and client using cryptographic methods. TH API Manager implements this with Two-way SSL over HTTPS.

Additionally, at the message level, the Gateway enforces security through:

• Policy-Level
• Endpoint-Level

The table below points out the difference between Policy-Level and Endpoint-Level security.

Policy-Level Security	Endpoint-Level Security
Secures messages between the application (client) and API Gateway (server)	Secures messages between the API Gateway (client) and the exposed services (server)
Authentication possible through HTTP Basic Authentication, OAuth 2.0, WS Security (SOAP)	Authentication possible through HTTP Basic Authentication
Usage Limit configured as Usage Policy and attached to Usage Plans at Proxy Endpoint-level	Usage Limit configured as Usage Policy and attached to Real Endpoint as Part of Endpoint configuration and applies to the backend as a whole
Applied by the Policies at runtime to the plans they are attached to	Applied for all service requests regardless of the policies attached to plans

Authentication

TH API Manager uses an Auth Server to control access to backend services, ensuring only valid, authenticated API calls are permitted. It supports the following authentication methods:

• Basic Authentication: Requires a username and password encoded in the request header. The Gateway validates these credentials at the Subscription-level.

• OAuth 2.0: An authorization framework for granting access tokens to third-party applications, allowing secure resource access on behalf of users. For details on OAuth types, refer to ‘Using OAuth in TH API Manager.’

• WS Security: Provides message-level security for SOAP messages, validating credentials at the Gateway-level to ensure safe exchanges between SOAP API endpoints and clients.

• Pass-Through Authentication: The Gateway does not validate credentials but forwards them to the backend server for authentication.

• API Linked to Backend Security: The Gateway replaces subscription-level credentials with backend security credentials, enforcing backend-level security instead of API subscription-level security.

Using OAuth in TH API Manager

OAuth allows third-party applications to access protected resources without sharing user credentials. For example, if you have private photos on Flickr and want to allow a content publishing site to access only some of these photos temporarily, OAuth can manage this access securely. Unlike sharing your username and password, OAuth provides a way to grant access with specific permissions while protecting your sensitive data.

Th API Manager supports OAuth 2.0 for consumer APIs and integrates with any OAuth Service Provider. It includes a standard OAuth server implementation. Key terms include:

• Access Token: Used in place of a username and password to access resources.
• Authentication: Verifying a user's identity with credentials.
• Authorization: Granting access rights to authenticated users.
• Authorization Grant: Credentials to obtain an access token.
• Authorization Grant Types: Different methods to provide authorization in OAuth 2.0.
• OAuth Server: Generates access tokens.
• Client/Client Application: An application registered in the TH API Manager Developer Portal.
• Client ID: Identifies the application publicly.
• Client Secret: Authenticates the application privately.
• Scope: Defines the API access level for subscriptions.
• End-user: The user of the client application.
• Refresh Token: Obtains a new access token after the old one expires.
• Resource: Protected data owned by the resource owner.

The tables below detail the activities related to OAuth authentication.

• Administrative activities for the Publisher and Developer portals.

Sl. No.	Task	Where	Documentation Path
1	The Application Developer registers their application	Developer Portal	Developer Portal > Manage Applications > Add an Application
2	The Publisher user approves the application	Publisher Portal	Publisher Portal > Manage Approvals
3	The Application Developer receives the Client ID and Client Secret	Developer Portal	Developer Portal > Manage Applications > View Application Details
4	The Application Developer manages their Access Tokens	Developer Portal	Developer Portal > Manage Applications > Get Access Token
5	The Publishers manage their Developers’ Access tokens	Publisher Portal	Publisher Portal > Manage Access Tokens

• Activities related to consuming exposed APIs from Developer portal via the TH API Manager Gateway.

Sl. No.	Task	Documentation Path
1	Making authenticated requests	Introduction > Key Concepts > Making Authenticated Requests
2	Gateway OAuth APIs for Access Token management	Gateway OAuth APIs

Roles in OAuth 2.0

OAuth defines four key roles:

• Resource Owner: The individual who authorizes an application to access their account. In TH API Manager, this is the publisher.

• Client: The application requesting access to the resource owner's account. The end-user must authorize the client, and this authorization is validated by the API.

• Resource Server: The server that stores protected resources and processes authenticated requests after the client has obtained an access token.

• Authorization Server: The server responsible for verifying the user’s identity and issuing access tokens to the client application.

Tokens

OAuth uses two types of tokens: Access Tokens and Refresh Tokens.

• Access Token: A string of characters used to access protected resources. In TH API Manager, Publisher users can view and revoke access tokens, while Developer users can generate, view, and revoke them.

• Refresh Token: A string of characters used to obtain a new Access Token when the current one expires or becomes invalid. It is typically used alongside an Access Token.

• Token Endpoint: The URL through which clients request Access Tokens from the Authorization Server.

Supported OAuth Grant Types

TH API Manager supports the following OAuth 2.0 Grant Types:

• Client Credentials:

  • The client application provides its Client ID and Client Secret to obtain an access token.
    1. The Publisher portal supplies the Client ID and Client Secret.
    2. The client requests an access token from the Authorization Server’s token endpoint with these credentials.
    3. The Authorization Server authenticates and validates the credentials, then issues an access token.

• Password:

  • Suitable when the Resource Owner fully trusts the client application. The client application uses the provided username and password to request an access token.
    1. The application developer gives the client the username and password.
    2. The client requests an access token from the Authorization Server’s token endpoint with these credentials.
    3. The Authorization Server authenticates and validates the credentials, issuing both an access token and a refresh token.

• Refresh Token:

  • Used with the Password Grant Type, requiring a Refresh Token to function.
    1. When the access token expires or becomes invalid, the client uses the Refresh Token to request a new access token.
    2. The client authenticates with the Authorization Server, presenting the Refresh Token.
    3. The Authorization Server validates the Refresh Token and, if valid, issues a new access token.

Multi-Scope OAuth Support

TH API Manager supports Multi-Scope OAuth for applications registered through the Developer portal. This feature allows applications to access specific subscriptions (defined by plan IDs) from a list of available options. When enabled, it prevents the use of a single subscription key to access all subscriptions under a user for a particular application.

With Multi-Scope OAuth, an application can access either all or a selective number of subscribed plans. For example, if Application A1 is subscribed to Plans P1, P2, and P3, it can by default access all three plans. However, with Multi-Scope OAuth, the application can be configured to access only specific plans (e.g., P1 and P2, but not P3). Additionally, Open Scope (or Read scope) allows unrestricted access to all scopes under a given application.

This support is particularly useful when multiple users with different roles (e.g., Admins and Developers) access the same application. Scopes can be defined to control which services are available to each user based on their role. For example, a Developer might need a specific scope to access certain services, while an Admin might need a different scope. Users provide their credentials along with the scope to obtain an access token. The Gateway validates both the token and the scope, granting access only if they are valid. Invalid scopes will result in errors from the Gateway.

OAuth Workflow in TH API Manager

1. Application Registration: The application developer registers their application in the TH API Manager Developer Portal.

2. Approval and Credential Retrieval: Once the application is approved in the Publisher portal, the Developer Portal displays the generated Client ID and Client Secret.

3. Token Request:

   • Client Credentials Grant: The client application sends the Client ID, Client Secret, and scope to the gateway to request an Access Token.
   • Password Grant: The client application sends the username, password, and scope to the gateway to request an Access Token.
   • Refresh Token Grant: The client application sends the refresh token and scope to the gateway to request a new Access Token.

4. Token Issuance: The OAuth Provider generates an Access Token and sends it to the TH API Manager Gateway, which then forwards it to the client.

5. API Consumption: The client uses the Access Token in all requests to consume exposed APIs.

6. Token Validation: The gateway validates the Access Token with the OAuth provider. If valid, the request is forwarded to the backend API. If invalid, the request is rejected. Note that the Access Token has an expiration time.

Registering an Application

To use OAuth with your application, developers must first register their client application in the TH API Manager Developer portal. This registration process provides the application with a Client ID and Client Secret, which are essential for requesting an Access Token.

Client ID and Client Secret

After registration, the service issues two client credentials:

• Client ID: A publicly exposed string used to identify the application.
• Client Secret: A confidential string used to authenticate the application’s identity to the service API. This secret must remain private between the application and the API.

Revoking an Access Token

Access tokens can be revoked by both API Publisher and Developer users, effectively canceling or invalidating the token. This can be done through the Publisher portal for Publishers and the Developer portal for Developers. Additionally, tokens can be revoked programmatically from within your application using the appropriate code.

info

Revoking an access token permanently deletes it from the system, making it unusable for future requests.

Making Authenticated Requests

To make authenticated requests, first generate an access token using one of the Gateway OAuth APIs. Include this access token in the Authorization header of your HTTP request as follows:

Authorization: Bearer <access token>

Two-Way SSL Security

Two-way SSL security ensures a secure connection between an API provider and an API client by requiring both parties to present certificates for mutual authentication.

• Server Authentication: The server authenticates itself to the client using a digital certificate and digital signature. This certificate, which contains a public key and cryptographic algorithm, is used by the client to verify the server's identity.

• Client Authentication: The client also presents a certificate to the server to prove its identity. This certificate contains identifying information and a digital signature to verify its validity. Client authentication is crucial when the server needs to restrict access to a specific group of users.

• Digital Signature: A digital signature is a cryptographic value attached to information to verify its origin and ensure it has not been altered. It is issued by a certifying agency and encrypted within the digital certificate. While anyone can decrypt this certificate, only the certifying agency can encrypt it. Browsers use the public key to decrypt the certificate and verify its legitimacy. Self-signed certificates are not recognized by browsers unless they are included in the list of certifying agencies.

How SSLs Work

SSL (Secure Sockets Layer) ensures secure communication between a server and a client by using encryption. Here's a brief overview of how SSL works:

1. Public-Private Key Pair:

   • SSL uses a public-private key pair for encryption. The server has a private key and a public key. The client has access to the server’s public key.

2. Encryption and Decryption:

   • Encryption: The sender encrypts the message using the recipient's public key.
   • Decryption: The recipient decrypts the message using their private key.

3. Two-Way SSL:

   • Server Authentication: The server provides its public key to the client, allowing the client to verify the server's identity.
   • Client Authentication: The server may also require the client to present a certificate to verify the client’s identity.

In essence, SSL ensures that data transmitted between the server and client is encrypted and secure from unauthorized access.

XSS Safety in TH API Manager

TH API Manager safeguards the Developer portal against cross-site scripting (XSS) attacks, which involve the injection of malicious code via web applications.

Key Points:

• XSS Safety Enabled:

  • User input is sanitized to remove malicious content before storing it in the database.
  • Provides protection against code-injection attacks.

• XSS Safety Disabled:

  • User input is stored directly without modification, potentially exposing the system to XSS attacks.

Configuration:

• XSS safety can be configured via the properties file. Consult the TH API Manager installation guide for instructions on enabling XSS safety.

info

XSS safety is currently supported only for the Developer portal.

Protected Vulnerabilities:

• Risky HTML Elements: Prevents harmful HTML tags from being stored.
• Event Handlers: Blocks JavaScript event handlers that can be exploited.

Allowed Elements and Protocols:

• Inline Formatting Elements: b ,i, font, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em

• Block Elements: p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote

• URL Protocols: http, https, mailto

Allowed CSS Elements
-moz-border-radius	border-bottom-width	font-style	pitch-range
-moz-border-radius-bottomleft	border-collapse	font-variant	quotes
-moz-border-radius-bottomright	border-color	font-weight	radial-gradient()
-moz-border-radius-topleft	border-left	height	rect()
-moz-border-radius-topright	border-left-color	image()	repeating-linear-gradient()
-moz-box-shadow	border-left-style	letter-spacing	repeating-radial-gradient()
-moz-outline	border-left-width	line-height	rgb()
-moz-outline-color	border-radius	linear-gradient()	rgba()
-moz-outline-style	border-right	list-style	richness
-moz-outline-width	border-right-color	list-style-image	speak
-o-text-overflow	border-right-style	list-style-position	speak-header
-webkit-border-bottom-left-radius	border-right-width	list-style-type	speak-numeral
-webkit-border-bottom-right-radius	border-spacing	margin	speak-punctuation
-webkit-border-radius	border-style	margin-bottom	speech-rate
-webkit-border-radius-bottom-left	border-top	margin-left	stress
-webkit-border-radius-bottom-right	border-top-color	margin-right	table-layout
-webkit-border-radius-top-left	border-top-left-radius	margin-top	text-align
-webkit-border-radius-top-right	border-top-right-radius	max-height	text-decoration
-webkit-border-top-left-radius	border-top-style	max-width	text-indent
-webkit-border-top-right-radius	border-top-width	min-height	text-overflow
-webkit-box-shadow	border-width	min-width	text-shadow
azimuth	box-shadow	outline	text-transform
background	caption-side	outline-color	text-wrap
background-attachment	color	outline-style	unicode-bidi
background-color	cue	outline-width	vertical-align
background-image	cue-after	padding	voice-family
background-position	cue-before	padding-bottom	volume
background-repeat	direction	padding-left	white-space
border	elevation	padding-right	width
border-bottom	empty-cells	padding-top	word-spacing
border-bottom-color	font	pause	word-wrap
border-bottom-left-radius	font-family	pause-after
border-bottom-right-radius	font-size	pause-before
border-bottom-style	font-stretch	pitch

LDAP support

LDAP support in TH API Manager allows users to authenticate using the Lightweight Directory Access Protocol. This protocol is used to access identity-related information stored on enterprise servers. In TH API Manager, LDAP serves as an alternative authentication method.

Users can be added to LDAP in two ways within TH API Manager:

1. Manually adding users via the Publisher Users screen (for Publisher users) or Developer Users screen (for Developer Users). This can be done using the "New User from LDAP" button available on each respective screen.

2. Enabling automatic user addition from LDAP when users log in via LDAP.

In both cases, users added are enabled for LDAP authentication. Additionally, TH API Manager supports adding roles through its "Fetch Roles from LDAP" plugin.

For guidance on configuring LDAP support, please refer to the TH API Manager Installation Guide. If you need instructions on writing and configuring the LDAP plugin, consult the "Fetch Roles from LDAP" Plugin Guide.

Usage Limits

Usage Limits are crucial for managing API performance and preventing downtime by controlling access to backend resources. By implementing Rate Limiting and Throttling Policies within subscribed Usage Plans, you can effectively manage incoming requests.

Rate Limiting: Rate Limiting is a server-side mechanism that restricts the number of incoming request calls to prevent overload. It defines a maximum number of requests that clients can make within a specified timeframe. For instance, a client might be allowed 300 requests every 5 minutes, 3000 requests per hour, or 12000 requests per day. Requests exceeding these limits are denied, and the client is prompted to retry after the designated period has elapsed.

This strategy ensures that API resources are protected from excessive traffic, reducing the risk of malfunctions and maintaining service reliability.

Throttling:

Throttling manages requests exceeding set limits by queuing them rather than rejecting them outright. Excess requests are held in a queue and processed in subsequent time slots. Once the call limit is reached, subsequent requests from the client are delayed to push them to the next available time slot. For instance, if an app generates excessive API calls due to poor coding, TH API Manager can apply predefined policies to throttle incoming calls, ensuring they are queued until the app is adjusted and the next call can be serviced.

Concurrency limit

Concurrency limit refers to the maximum number of simultaneous API requests allowed within an API for a specific API Resource or Operation at any given time. This limit, often denoted as MCT (Maximum Concurrent Connections), determines how many requests can be processed concurrently by the backend infrastructure. It becomes active when messages are ready to be sent to the backend, ensuring that the system manages and controls the volume of concurrent requests effectively.

Usage Policy Library

The Usage Policy Library in TH API Manager manages configurations that enforce Usage Limits on API traffic. These policies, applied through the Gateway, include Rate Limits and Throttling to regulate incoming traffic and protect backend systems from overload.

Within the Usage Policy Library, you can:

• Create new Usage Policies.
• Modify or delete existing policies.
• Enforce these policies through the Gateway.

Usage Policies can be tailored based on the specific restrictions you want to impose on API calls. They are categorized into Rate Limiting and Throttling options. When defining Usage Policies and storing them in the Library, you can attach them to Usage Plans. During the creation of Usage Plans, TH API Manager allows you to select and apply these policies at the Plan level. This enables you to manage traffic limits uniformly across all resources/operations within a plan or apply policies individually to specific resources as needed.

Transformations

TH API Manager, facilitated through its Gateway, serves as a centralized hub for transformations, offering several capabilities:

1. Custom Content Modifications: Users can modify, inject, or remove content within Request and Response headers and payloads.

2. Protocol Exchange: The Gateway supports changing message exchange protocols between REST and SOAP, enabling conversions such as JSON to XML and vice versa.

3. User-provided JavaScript: Users can upload JavaScript to facilitate complex transformations, such as converting REST with XML or JSON payloads into SOAP requests, and vice versa.

Transformations in TH API Manager are managed at two distinct levels:

• API Level: Transformations applied globally across all Resources and Operations within an API.
• Resource/Operation Level: Specific transformations applied to individual Resource or Operation endpoints.

During runtime, when a message (e.g., a request to an API Resource or Operation) undergoes transformation, it first encounters API-level transformations. If applicable, further transformations specific to the Resource or Operation are then applied.

info

TH API Manager does not perform validation or store user-provided scripts for future use. Therefore, it is essential for users to validate scripts before utilization and retain them for future needs.

Data Recording

Data Recording in TH API Manager logs API Requests and Responses, which can be utilized for analytics and billing. Users choose whether to log data and can specify actions like adding, removing, or masking fields (to protect sensitive data) from message payloads and headers during recording. Enabled data is logged in both application logs and the transactional database. Users can upload scripts for each resource/operation based on a default template, using the payload as script input.

Life cycle of Artifacts and Approval Workflows

APIs and other artifacts have independent life cycles from the back-end service they rely on.

THAPIM provides tools for managing the life cycles of APIs, as well as additional artifact kinds such as API Packs, Usage Plans, and Usage Policies.

In THAPIM, an artifact's life cycle consists of the following major states:

State	Description
Draft	A freshly created artifact. If it’s an API, or API Pack, it is not visible to consumers yet. None of them are deployed to the API Gateway.
Approved	An artifact that has been approved. If it’s an API, it is ready to be bundled into a Pack and monetized. Other artifacts are ready to be deployed to the server.
Published	An artifact that has been published after it is approved and successfully deployed to all Gateways.
Deprecated	An artifact that, though active, is marked for retirement or is close to being put out of use. Deprecated APIs and API Packs stay active on the server for existing subscribers.
Retired	An artifact that is no longer in use in the Publisher or Developer portal.

info

When Automatic Workflow for the artifact is not activated from the Global Configurations menu, it undergoes an interim state.

There are other intermediate states that supplement the primary states:

Submitted for Approval - When an artifact in the Draft State is sent for approval before proceeding to the Approved State.

Submitted for Deprecation - When an artifact in the Approved State is sent for approval before moving to the Deprecated State.

Submitted for Retire - When an artifact in the Deprecated State is provided for clearance to move to the Retired Status.

Approved, awaiting approval for editing - After an artifact has been approved, you may use the Open for Editing tool to edit it.

Published, Awaiting Approval for Editing - When you use the Open for Editing capability to edit an artifact after it has been published.

An API, API Pack, Usage Plan, or Usage Policy must be submitted for approval before moving on to the next State, which is when it shows in the Approval Requests list. When a Publisher user authorizes the artifact, it moves to the next stage of its life cycle.

Gateway Synchronization

Gateway Synchronization involves transferring configurations from the portal to the Gateway to enable them to function during runtime.

The Gateway utilizes two methods for synchronization: Manual Sync and Auto Sync. Below is a table that outlines and compares each method:

Manual Sync	Auto Sync
Applies to configurations that the user needs to propagate to make them operational in the Gateway.	Certain configuration changes get propagated automatically to the Gateway upon user submission.
Required on Approved API Versions, Approved Usage Plans, and Approved Named Usage Policies.	Changes automatically synced include Backend Endpoints, Global Configurations for Fault and Response codes and Response messages, and Subscription-level Configurations.
Enables the user to ensure data integrity in case of synchronization errors.	Data integrity is handled internally.
Has an associated Manual Rollback feature for Approved API Versions, Usage Plans, and Named Usage Policies.	No Rollback required as changes occur automatically without user intervention.

Rollback

TH API Manager facilitates restoring the Gateway to a previously defined state. To accomplish this, utilize the Rollback option subsequent to syncing changes from the portal, particularly when reverting recent configurations is necessary.

Developer Portal

The Developer portal serves as a web platform designed for application developers. It offers tools for discovering, testing, and integrating APIs into their applications. Developers register on the portal to explore available APIs and subscribe to Usage Plans that include the APIs they intend to use.

Key features of the Developer portal include:

• API Discovery through the API Store
• Developer Onboarding and Sandbox Testing
• Generation of Client IDs and App Keys
• Developer Administrative Services: Application Management, Subscription Management, Bookmarks, etc.
• API Documentation
• Discussion Forum
• Usage Analytics

Application

An application, within the realm of APIs, is a software program that leverages APIs to deliver useful services to its users. Developers of such applications are spared from reinventing common functionalities by utilizing APIs, which enable integration of essential features directly into their software. This approach allows developers to concentrate on coding the core aspects of their applications.

For instance, an application designed to assist users in locating rental apartments can utilize Craigslist’s API to access listing data and employ a mapping API such as Google Maps to pinpoint precise apartment locations.

Developer portal customization

Developer portal customization refers to the ability to alter the appearance and functionality of the Developer portal to align it with your organization's branding and strategic requirements. This customization allows you to make various adjustments such as modifying category structures, incorporating background images, banners, and icons into API Packs, and integrating additional content using a Content Management System (CMS).

With category hierarchies, you can redefine how API Packs are presented in the API Store, enhancing the portal's usability and visual appeal. TH API Manager initially provides a standard version of the Developer portal, where each publisher receives a base implementation. This setup enables publishers to freely modify HTML, CSS, and JavaScript files as necessary, ensuring the portal meets specific business needs and aesthetic preferences over time.

API Store

An API Store is essentially a marketplace within a Developer portal, organized into categories, where developers can browse and search for various API Packs. Each API Pack has a detailed view available, offering access to a Sandbox for testing APIs. The Store also acts as a gateway to inner pages where developers can subscribe to API Packs, access API documentation, and engage with other developers through a Discussion Forum.

TH API Manager provides tools for users to manage the visibility of API Packs within the API Store. This capability ensures that only relevant and useful API Packs are prominently displayed to developers, enhancing their experience by focusing on pertinent offerings.

Sandbox

The Sandbox in TH API Manager, powered by Swagger, allows app developers to test APIs before integrating them into their applications. This environment provides a user-friendly interface where developers can input parameters and observe how APIs behave.

Documentation accompanying the Sandbox enables direct API calls from within the interface. API details, including resource paths, HTTP methods (for REST), parameters, response codes/types, and error codes (for SOAP), are extracted from YAML or WSDL files based on Swagger or WSDL specifications provided by API publishers. This setup supports thorough testing and seamless integration of APIs into applications.

API Subscription

An API Subscription occurs when a developer purchases a Usage Plan to track and monetize their API usage. This involves paying a fee for accessing APIs within the plan and agreeing to a specified validity period. Subscriptions can optionally renew automatically upon expiry. Each subscription is linked to a Usage Plan that defines usage limits.

TH API Manager includes a specialized module for managing these subscriptions, ensuring effective oversight and control throughout their lifecycle.

Statistics

The Statistics feature in the Developer portal allows API developers to gain insights through charts and graphical representations. It provides detailed information on:

• Traffic generated by APIs
• Quota usage
• Traffic generated by applications
• Errors and timeouts

This feature helps developers analyze and understand how their APIs and applications are performing, facilitating informed decisions and optimizations.