TIBCO® API Exchange

Concepts
Software Release 2.0
November 2013

Two-Second Advantage®
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED
OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED
ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED
SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR
ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A
LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE
AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER
LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE
SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE
LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED
IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS
AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN
AGREEMENT TO BE BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright laws and
treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO
Software Inc.
TIBCO, The Power of Now, TIBCO , TIBCO ActiveMatrix, TIBCO ActiveMatrix BusinessWorks, TIBCO
Administrator, TIBCO ActiveSpaces, TIBCO Designer, TIBCO Enterprise Message Service, TIBCO Hawk, TIBCO
Runtime Agent, TIBCO Rendezvous, are either registered trademarks or trademarks of TIBCO Software Inc. in
the United States and/or other countries. EJB, Java EE, J2EE, and all Java-based trademarks and logos are
trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
All other product and company names and marks mentioned in this document are the property of their
respective owners and are mentioned for identification purposes only.
THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL
OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME
TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC
OPERATING SYSTEM PLATFORM.
THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.
CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE
INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE
IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THIS DOCUMENT AT ANY TIME.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR
INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING
BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
Copyright © 2013 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
 | iii

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
TIBCO® API Exchange Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
TIBCO® API Exchange Gateway Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
TIBCO® API Exchange Manager Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
Other Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv

Chapter 1 Concepts Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

TIBCO API Exchange Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
TIBCO API Exchange Concepts Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Product Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2 API Management Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

What is an API? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
APIs as Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Partner Identity and Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
API Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
OAuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Partner Authorization and Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Functional Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
API Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 3 API Gateway Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Gateway Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Gateway Functional Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Design Time Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Run-Time Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

TIBCO API Exchange Concepts

iv
|
Gateway Operational Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Gateway Management Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Analytics Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Design Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Facade Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Message Processing Life Cycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Mappings and Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Throttle Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Message Exchange Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Orchestration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

TIBCO API Exchange Concepts

 Figures v
|

Figures

Figure 1 Entity Relationship for Products, Plans, Subscriptions, and Applications . . . . . . . . . . . . . . . . . . . . 10

Figure 2 Functional Diagram of API Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Figure 3 Gateway Cluster. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Figure 4 Facade Service and Target Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

TIBCO API Exchange Concepts

vi
| Figures

TIBCO API Exchange Concepts

 Tables vii
|

Tables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

TIBCO API Exchange Concepts

viii
| Tables

TIBCO API Exchange Concepts

 | ix

Preface

TIBCO® API Exchange enables the building of API marketplaces, where service
providers and consumers come together to create, host, manage, learn about, and
use open APIs.

Topics

• Related Documentation, page x

• Typographical Conventions, page xii
• Connecting with TIBCO Resources, page xiv

TIBCO API Exchange Concepts

x
| Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO® API Exchange Documentation

The TIBCO API Exchange Documentation contains:
• TIBCO API Exchange Concepts Read this document to get an overview of API
Exchange concepts, workflow, and deployment.
• TIBCO API Exchange Getting Started. Provides an overview of the tasks
required to install, configure, and deploy TIBCO API Exchange.
These documents are included as part of the API Exchange Manager
documentation.

TIBCO® API Exchange Gateway Documentation

The following documents form the TIBCO API Exchange Gateway
documentation set:
• TIBCO API Exchange Gateway Installation Read this manual for instructions
on site preparation and installation.
• TIBCO API Exchange Gateway User’s Guide Read this manual for instructions
on how to configure and use this product.
• TIBCO API Exchange Gateway Release Notes Read the release notes for a list
of new and changed features. This document also contains lists of known
issues and closed issues for this release.

TIBCO® API Exchange Manager Documentation

• TIBCO API Exchange Manager Installation Read this manual for instructions
on site preparation and installation.
• TIBCO API Exchange Manager Administration Read this manual for
information on how to set up users and user groups, add APIs, and manage
products and plans.
• TIBCO API Exchange Manager Release Notes Read the release notes for a list
of new and changed features. This document also contains lists of known
issues and closed issues for this release.

TIBCO API Exchange Concepts

 Preface xi
|

Other Documentation
You might find it useful to read the documentation for the following:
• Joomla! - See http://docs.joomla.org.
• Example project hosted on GitHub: Adapter Code for TIBCO API Exchange and
Joomla!. See https://github.com/API-Exchange/JoomlaAdapter/wiki.

TIBCO API Exchange Concepts

xii
| Typographical Conventions

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use
ENV_NAME TIBCO products are installed into an installation environment. A product
installed into an installation environment does not access components in other
TIBCO_HOME
installation environments. Incompatible products and multiple instances of the
<ProductAcron same product must be installed into different installation environments.
ym>_HOME
An installation environment consists of the following properties:
• Name Identifies the installation environment. This name is referenced in
documentation as ENV_NAME. On Microsoft Windows, the name is
appended to the name of Windows services created by the installer and is a
component of the path to the product shortcut in the Windows Start > All
Programs menu.
• Path The folder into which the product is installed. This folder is referenced
in documentation as TIBCO_HOME.
TIBCO <ProductName> installs into a directory within a TIBCO_HOME. This
directory is referenced in documentation as <ProductAcronym>_HOME. The
default value of <ProductAcronym>_HOME depends on the operating system.
For example on Windows systems, the default value is
C:\tibco\<ProductAcronym>\<ReleaseNumber>.

code font Code font identifies commands, code examples, filenames, pathnames, and
output displayed in a command window. For example:
Use MyCommand to start the foo process.

bold code Bold code font is used in the following ways:

font
• In procedures, to indicate what a user types. For example: Type admin.
• In large code samples, to indicate the parts of the sample that are of
particular interest.
• In command syntax, to indicate the default parameter for a command. For
example, if no parameter is specified, MyCommand is enabled:
MyCommand [enable | disable]

TIBCO API Exchange Concepts

 Preface xiii
|

Table 1 General Typographical Conventions (Cont’d)

Convention Use
italic font Italic font is used in the following ways:
• To indicate a document title. For example: See TIBCO ActiveMatrix
BusinessWorks Concepts.
• To introduce new terms For example: A portal page may contain several
portlets. Portlets are mini-applications that run in a portal.
• To indicate a variable in a command or code syntax that you must replace.
For example: MyCommand PathName

Key Key name separated by a plus sign indicate keys pressed simultaneously. For
combinations example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the
other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for
example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply
the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example,
data loss or corruption if certain steps are taken or not taken.

TIBCO API Exchange Concepts

xiv
| Connecting with TIBCO Resources

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and
resident experts. It is a place to share and access the collective experience of the
TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety
of resources. To register, go to http://www.tibcommunity.com.

How to Access TIBCO Documentation

You can access TIBCO documentation here:
http://docs.tibco.com

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact
TIBCO Support as follows:
• For an overview of TIBCO Support, and information about getting started
with TIBCO Support, visit this site:
http://www.tibco.com/services/support
• If you already have a valid maintenance or support contract, visit this site:
https://support.tibco.com
Entry to this site requires a user name and password. If you do not have a user
name, you can request one.

TIBCO API Exchange Concepts

 |1

Chapter 1 Concepts Overview

This chapter provides an overview of TIBCO API Exchange and summarizes the
basic organization of the concepts and guide.

Topics

• TIBCO API Exchange Overview, page 2

• TIBCO API Exchange Concepts Overview, page 3

TIBCO API Exchange Concepts

2
| Chapter 1 Concepts Overview

TIBCO API Exchange Overview

TIBCO® API Exchange is an integrated solution for creating, hosting, and

managing open APIs. It is designed to meet the security and web scale
requirements of developers who deliver open APIs to mobile devices and the
business needs of companies that want to use open APIs to develop new revenue
streams.
Open application programming interfaces (APIs) enable a new business model,
providing innovative ways to expand brand value and routes to market, and
create new value chains for intellectual property.
TIBCO API Exchange includes three solution components:
• TIBCO® API Exchange Manager enables API providers to design, document,
and manage the lifecycle of open APIs that can be exposed to developers
inside or outside of their company. A self-service portal for developers is
provided, allowing them to subscribe to open APIs, search and browse
available APIs and documentation, request developer keys, and test API
functionality.
• TIBCO® API Exchange Gateway allows runtime management and
governance of APIs through configuration of rules and policies that define
how specific events will be handled throughout the processing pipeline of an
API call. Policy definitions range from edge policies related to authentication,
load balancing, throttling, and routing to service-specific mediation and
security certificate management, message transformation, and content based
routing.
• TIBCO Spotfire® provides optional analytics capability for understanding
API usage metrics and patterns. Users can create custom reporting
dashboards for monitoring SLAs and KPIs to measure and improve on the
success of open API initiatives

TIBCO API Exchange Concepts

 TIBCO API Exchange Concepts Overview 3
|

TIBCO API Exchange Concepts Overview

A few concepts are essential for a thorough understanding of TIBCO API

Exchange. If you are new to TIBCO API Exchange, it is helpful to review these
concepts.
• API Management The process of managing the creation, proxying, assembly,
securing, scaling and socializing web APIs. TIBCO API Exchange provides
tools for performing all of the steps in this process.
For detailed information on TIBCO API Exchange concepts, see Chapter 2,
API Management Concepts
• TIBCO API Exchange Gateway A SOA gateway that allows runtime
management and governance of APIs through configuration of rules and
policies that define how specific events will be handled throughout the
processing pipeline of an API call.
TIBCO API Exchange Gateway concepts include functional concepts such as
the overall gateway design, facade service, throttle policies, and so on. For
detailed information on TIBCO API Exchange Gateway Concepts, see
Chapter 3, API Gateway Concepts.

Product Components
This section describes the main product components.

TIBCO API Exchange Gateway

The exchange gateway is the centralized policy enforcement point that receives
requests and applies partner-specific policies.

TIBCO API Exchange Manager

Implements the API management functionality of API Exchange. Facilitates
assigning user roles, the creation of APIs, products, and applications, and enables
a subscription model that lets your business partners easily subscribe to the APIs
and applications that application developers set up.

Adapter Code for TIBCO® API Exchange and Joomla! 2.0

Provides an interface that implements an API management portal based on
Joomla.

TIBCO API Exchange Concepts

4
| Chapter 1 Concepts Overview

TIBCO API Exchange Concepts

 |5

Chapter 2 API Management Concepts

This chapter describes API Management concepts and explains how TIBCO® API
Exchange enables the packaging and promotion of APIs as standardized products
and the creation of API management portals for internal and external partners.

Topics

• What is an API?, page 6

• APIs as Products, page 7
• Partner Identity and Authentication, page 8
• Applications, page 9
• Partner Authorization and Subscriptions, page 10
• User Management, page 11
• Functional Overview, page 12
• API Explorer, page 13

TIBCO API Exchange Concepts

6
| Chapter 2 API Management Concepts

What is an API?

An API, or Application Programming Interface, is a programming specification

for how two components can interact—that is, how a programmer would write
code in one component to talk to the other one. If they are communicating
between processes or machines we could also say the API is a service specification
or interface.
The API or service will have a URL where it can be accessed as an endpoint.
The interface includes one or more different message exchange patterns
supporting different functions, which we call operations. Consider a
book-oriented API with three operations:
Book (API)—https://api.books.com
• GetBookByTitle Find books by title (Operation)
• GetBookByAuthor Find books by author name (Operation)
• AddBook Creates a new book (Operation)
Each operation will also, if supported by the message exchange pattern, have an
input and output message defined. For example:
GetBookByTitle

• Request: Title
• Response: Book {Title, Author, ISBN, Publisher}
To be really helpful, the service provider might also offer the programmer (service
consumer) example code, showcase applications, and an ability to try/test the
service via their web browser.
While TIBCO API Exchange Gateway manages access and communication
between the two components – the service interaction, TIBCO API Exchange
Manager supports the people aspect – discovering, learning, testing and using
APIs. It thus manages people-oriented aspects such as documentation, packaging,
evaluation and pricing.
TIBCO API Exchange Manager includes support for SOAP and REST APIs, such
as APIs that work with SOAP and REST specifications (WSDL and Swagger
respectively).

TIBCO API Exchange Concepts

 APIs as Products 7
|

APIs as Products

Companies of all shapes and sizes are realizing agility through service-oriented
approaches to software development. Increasingly the service provider and
consumer are from different development groups and even different companies,
and with the increased use of third-party services in mission critical systems we
now see the notarization of service agreements as legal contracts.
As SOA environments grow, as the number of services increases, the numbers of
interdependencies, participants and service agreements also grows, creating an
SOA management problem. SOA lifecycle management tools help standardize
and automate approval chains; they help manage the contract negotiation
between service consumer and provider where parties come together to agree on
functional specifications, interfaces and quality of service. Companies are
routinely managing dozens of partners—expanding the influence of their
business and their agility.
To take the next step, to expand influence and agility through hundreds or
thousands of partners, requires a different approach. The artisan might be able to
sell customized goods from their workshop to individuals but will often
standardize the features, price structure and quality in order to take them to the
mass market—they will create product.
A product is the commercial offering; the packaging of the API. A product is a
primary concept within TIBCO API Exchange and includes:
• A package of one or more APIs (APIs can be in multiple products too)
• An entry in the product catalog (name may be different from the APIs)
• Quality of service plans
A plan is an offering of a product for a specific capacity:
• Plan name and description
• Quota—maximum calls per day
• Rate limit—peak calls per second
• Subscription model—active on request or manual approval
• Price
• Custom—yes / no—One-off custom plans can also be created for specific
consumers.

TIBCO API Exchange Concepts

8
| Chapter 2 API Management Concepts

Partner Identity and Authentication

Unless an API is completely open, a method is needed to indicate which partner

organization is calling it so the gateway can authorize access. The approach taken
for identification may change depending on the type of service, whether the
partner is internal or external, and on the privacy and security requirements.
An API might support multiple identification methods and the same partner
might be identified through multiple credentials. TIBCO API Exchange Gateway
supports a range of identity and authentication mechanisms, including API keys,
OAuth, mutual SSL, WS-Security (SAML, User name, X.509, LDAP), HTTP Basic,
and Kerberos, but also makes it easy to integrate with existing databases and
identify management systems.
TIBCO API Exchange Manager allows partners to manage their own API keys
and OAuth credentials. A partner can create multiple keys.

API Key
An API key is an opaque token passed as an HTTP header or as a URL parameter
with each request. For example,
https://api.books.co/Books/Now?apikey=195-532d7700-44fe-9175-3a9d4
08a7286

OAuth
OAuth credentials (Client id and Client secret) are used to authenticate access and
generate an OAuth token which is passed with each API call. Grant types
supported via OAuth are:
• Authorization code authorizing apps running on a web server
• Resource owner password authorizing trusted apps
• Client credentials application access (no user credentials)
For Implicit flows (where the secret is not used) an API Key can use used.

TIBCO API Exchange Concepts

 Applications 9
|

Applications

An application is the partner component that calls or consumes the API. The API
may be called from an application running under direct control of the partner
running from a data center server for example, or may run outside their control
on a mobile phone or desktop.
A partner registers each application with TIBCO API Exchange Manager, which
allocates a unique app-specific key. In addition, this allows the partner to see their
API usage over time against each application. They can also disable access to APIs
on a per-application basis by revoking or resetting keys.

TIBCO API Exchange Concepts

10
| Chapter 2 API Management Concepts

Partner Authorization and Subscriptions

After partner identity verification and (and for some identity methods a separate
authentication step), the gateway enforces authorization.
The gateway enforces access to specific operations by partner, or by partner
group—a named collection of partners. Access is configured through the gateway
administrator or through TIBCO API Exchange Manager, where partners are
granted access to product plans through subscriptions.
A subscription may be requested by a partner and is either automatically created
(if auto approve is true) or sent to an administrator for review. If approved, the
administrator then creates a subscription—against an existing or custom plan.
The partner then activates the subscription for the specific applications that will
use that API.
Figure 1 illustrates the relationship between partners and APIs.

Figure 1 Entity Relationship for Products, Plans, Subscriptions, and Applications

TIBCO API Exchange Concepts

 User Management 11
|

User Management

The API management portal supports two classes of users. Partners who are
learning about and subscribing to APIs, and Hosts who are publishing the APIs
and managing products and partner access. A user is associated with either a host
or partner organization. There is currently support for one host and many partner
organizations; a user may belong to one organization.
Partner organization roles include:
• Application Developer Creates applications and keys; learns about and tests
APIS; requests subscriptions.
• Application Manager Adds ability to view partner analytics.
Host Organization roles include:
• Product Manager Manages products and plans including content; analytics.
• Partner Administrator User and subscription management; analytics.
• Host Administrator Is responsible for portal administration.

TIBCO API Exchange Concepts

12
| Chapter 2 API Management Concepts

Functional Overview

A typical deployment for API Management includes four collaborating

subsystems. The API management portal that provides the front-end user
interface portals for API providers and consumers sends key requests and
activated subscriptions to TIBCO API Exchange Manager, which distributes
policies to API Gateways that enforce policies and log statistics to API Analytics,
which presents relevant information within the portal for use by API -providers
and consumers. Figure 2 shows a functional diagram of TIBCO API Exchange
Manager.

Figure 2 Functional Diagram of API Management

TIBCO API Exchange Concepts

 API Explorer 13
|

API Explorer

An important characteristic of an open API is a low barrier to entry; the open API
is easy to access, learn about, and integrate. Ease of use includes the ability for an
application developer to test an API without installing client-side software or
having to write code.
Developers using SOAP services are familiar with downloading a standardized
machine readable WSDL specification and using a tool such as SoapUI or Eclipse
to test an API.
To support REST, TIBCO API Exchange supports the Swagger specification, a
standard for describing a REST-ful services for which interactive documentation
and a test harness can be generated.
The Adapter Code for TIBCO® API Exchange and Joomla! includes an example of
how the Swagger UI can be integrated into an API managment portal.

TIBCO API Exchange Concepts

14
| Chapter 2 API Management Concepts

TIBCO API Exchange Concepts

 | 15

Chapter 3 API Gateway Concepts

This chapter describes the key concepts for understanding the TIBCO API
Exchange Gateway component.

Topics

• Gateway Overview, page 16

• Design Time Components, page 18
• Run-Time Components, page 19
• Design Concepts, page 21

TIBCO API Exchange Concepts

16
| Chapter 3 API Gateway Concepts

Gateway Overview

The TIBCO API Exchange Gateway provides centralized runtime management

and governance of APIs through configuration of policies and rules.

Cluster
Gateway engines or instances may be clustered across many processes and/or
machines. For fault tolerance each instance maintains a local copy of their
configuration.
A gateway cluster can be geographically located near API consumers or providers
for performance.
Figure 3 shows a gateway cluster.

Figure 3 Gateway Cluster

Gateway Functional Overview

The TIBCO API Exchange Gateway provides:
• Authentication and Authorization

TIBCO API Exchange Concepts

 Gateway Overview 17
|

• Throttle Management
• Routing
• Cache management
• Transformation and orchestration
• Logging and statistics

TIBCO API Exchange Concepts

18
| Chapter 3 API Gateway Concepts

Design Time Components

TIBCO API Exchange Gateway includes the following design time components:
• TIBCO API Exchange Gateway Configuration GUI Using the configuration GUI,
you can configure partner data, partner operations, partner groups, services,
operations, mappings, throttles, error maps, schemas and routing
information.
• TIBCO API Exchange Gateway Studio The Gateway Studio is a design time
environment that allows you to design and develop custom extensions.
Custom extensions can be integrated with the default implementation to
customize the default behavior of the gateway core engine.

TIBCO API Exchange Concepts

 Run-Time Components 19
|

Run-Time Components

The TIBCO API Exchange Gateway run-time components consist of an:

• Operational Layer
• Management Layer
• Analytics Layer

Gateway Operational Layer

The Gateway operational layer scales as processing demands increases, primarily
based on the volume of requests. The operational layer consists of the following
components:
• Apache HTTP Server
• Core Engine
• Cache Agent

Apache HTTP Server

The Apache layer is used to terminate the incoming HTTP(s) transport and
communicate with Facade component to forward the requests for further
processing. Optionally, a JMS Server can be deployed to use the JMS transport.

Core Engine
The core engine is a high-performance event-based service-request routing engine
that receives requests as events and uses the rules engine to determine where
requests are handled.

Cache Agent
The cache agent stores the cache data for all objects of the cluster.

Gateway Management Layer

The Gateway management layer has the following sub-components:
• Central Logger The Central Logger provides the centralized of messages in a
database or file.

TIBCO API Exchange Concepts

20
| Chapter 3 API Gateway Concepts

• Global Throttle Manager The Global Throttle Manager manages the Façade
Throttle Manager and Service Throttle Manager. This component maintains
the state of all global throttles in both Façades (Façade Throttles) and Routers
(Service Throttles).
• Cache Clearing Manager The Cache Clearing Manager component clears the
cache based on the size and age of the cached values.
• Monitoring and Management Server The Monitoring and Management Server
is the central management component that allows you to monitor the status
and manage the operational tasks of all components in the Gateway cluster.
• Gateway Reporting (Optional) The Gateway Reporting component generates
the various type of reports based on the data logged in by the Central Logger
component. This component integrates with the TIBCO Spotfire product to
display data metrics.

Analytics Layer
The analytics database receives runtime information and statistics from one or
more Central Loggers that may represent one or more gateway clusters.
Information that may be captured includes KPIs (aggregated statistics or Key
Performance Indicators), logs of each request/response (transaction logs) and for
message transformation and event processing steps.

TIBCO API Exchange Concepts

 Design Concepts 21
|

Design Concepts

This section provides further details on the operational features of the TIBCO API
Exchange Gateway.
The core engine contains the following main sub-components:
• Facade The Facade provides a public northbound interface for the gateway to
receive requests for a given API with a given binding (for example, SOAP
over HTTP or SOAP over JMS).
• Router The Router receives the requests from the Facade and routes it to the
appropriate service handler.

Facade Service
A facade service is any application service or API that the gateway offers.
Typically the service is an intermediary to one (or more) target services outside the
gateway.
A facade service may also be known as a proxy service or virtual service,
especially if the interface of the facade and target services are the same. The
gateway facilitates a loose coupling between the facade and target service by
managing interfaces, policies and configuration information for either the facade
service or target service.

TIBCO API Exchange Concepts

22
| Chapter 3 API Gateway Concepts

Figure 4 Facade Service and Target Services

Router
The Router receives the requests from the Facade and routes it to the appropriate
service handler.

TIBCO API Exchange Concepts

 Design Concepts 23
|

Message Processing Life Cycle

The gateway core engine uses a staged event-driven architecture. Request and
response messages are processed internally as events with processing steps
determined dynamically by the engine based on applicable policies.

Mappings and Transformations

TIBCO API Exchange Gateway provides message transformations using
mappings. Combined with throttling, this allows you to implement business
agreements to enforceable policies.
The mapping capabilities of TIBCO API Exchange Gateway allow you to
decouple the operation and target services by providing a mutual common
canonical message format between the two.
TIBCO API Exchange Gateway supports mappings at various levels and reduces
the number of point-to-point mappings between gateway facade operations
(exposed by the gateway) and gateway target operations.
TIBCO API Exchange Gateway provides transformation of request and response
messages at following four points:

TIBCO API Exchange Concepts

24
| Chapter 3 API Gateway Concepts

• Facade request handler to Router boundary: After the request has been
received by Facade request handler and before it is been passed to the Router.
• Router to Service endpoint handler boundary: After the request has been
routed but before it is passed to the service endpoint handler.
• Service Endpoint handler to Router boundary: After the response has been
received from the service endpoint handler and before it is passed to the
Router.
• Router to Facade request handler After the response has been routed from the
router to the facade request handler and before the response is sent back to the
original requestor.
Additionally, facade request and response transformations can be overridden on a
partner specific basis.
For more information on mappings and transformations, see the “Mappings and
Transformations” section in chapter 5 of the TIBCO API Exchange Gateway
User’s Guide, “Transaction Pipeline Processing.”

Throttle Policies
Throttle policies allow usage or other limits to be enforced. They allow you to
define the maximum number of requests that are handled by a facade or target
operation in a defined time interval. You must define the maximum count and the
time interval for a throttle.
Throttles define a condition for a type and metric (entity). API Exchange Gateway
checks the condition for an incoming request before processing the request. For
example, you can define a condition to allow only 5 client requests within 10
seconds to the backend service for a partner request.
There are two main categories of throttles:
• Facade throttles Support service level agreements with consumers, for
example, Partner and Partner plus Operations.
• Target throttles Support service level agreements with providers and are
applied on the Target Service operation.

Throttle Types
There are four kinds of throttles
• Rate Rate throttle is a simple throttle that allows the requests to pass-through
until a limit is reached for a time interval. The rate throttle is always increased
on the request. A throttle may be incremented by a count of requests, size of a

TIBCO API Exchange Concepts

 Design Concepts 25
|

payload or can be based on content. For example, a throttle based on order

totals.
• Quota Quota throttle is quite similar to the Rate Throttle, but it uses a much
larger count over much longer intervals (such as days). The quota throttles are
increased on the request. For a quota throttle, you must define throttle interval
(in hour) and throttle max count.
• High Water Mark High Water Mark throttle is similar to the Rate Throttle, but
this throttle also decrements the count after the passed-on requests are
completed and the response is ready to return to the requestor. This means
that the High Water Mark throttle are increased on the request and decreased
on the response. You must define a throttle max count for a high water mark
throttle.
• Error Error Throttles acts as a Rate Throttle in logic, but this throttle counts
the error responses, as opposed to the requests. The throttle count of an error
throttle is increased on the error responses.

Routing
Routing allows the directing of requests to specific target services based on
operation, partner, version or message content or operation.

Message Exchange Patterns

A message exchange pattern (MEP) defines the sequence and cardinality of
messages sent between the provider and the consumer for an interaction. MEPs
contain both normal and fault messages. The gateway supports several different
styles of message exchange as well as the ability to mediate between them.
The service gateway supports the following patterns:
• Request/Acknowledge (One-Way) A consumer sends a message to a provider
that provides a status response. Also known as Fire and Forgot, and In-Only.
• Synchronous Request-Response (Sync) A consumer sends a message to a
provider with expectation of response over the same client connection. The
provider sends a response message or fault and the consumer responds with a
status.
• Asynchronous Request-Response (Async) A consumer sends a message to a
provider with expectation of a callback of a response. The provider
acknowledges the request. The provider then sends a response message or
fault and the consumer responds with a status.
• Consume Message A provider sends a message to a consumer.

TIBCO API Exchange Concepts

26
| Chapter 3 API Gateway Concepts

The service gateway supports different MEPs between (1) the façade consumer
and the façade service and (2) between the target consumer and the target service.
Some common combinations are:

Orchestration
Orchestration models determine how requests are handled. The TIBCO API
Exchange Gateway provides the following orchestration models:
• Parallel Orchestration (also called Enumeration)
With parallel orchestration, a single inbound request is split into a set of
multiple outbound sub-requests. Each sub-request may be routed differently
to various service endpoints. After processing and receiving the responses for
each sub-requests, all responses are recombined into a single response
message for the original inbound request.
• Sequential Orchestration
Sequential orchestration allows you to access multiple target endpoints by
making a number of sequential calls to fulfill or authorize a request. With
sequential orchestration, there is a primary outbound target invocation,
preceded by one or more secondary target invocations.
Sequential orchestration may use the associative and responses cache features
to accelerate the processing of subsequent requests, which helps to minimize
the load on back-end systems.

Partners
In the TIBCO API Exchange Gateway, you can define partners and partner groups
and specify processing for them. You can configure:
• Information that identifies a partner
• The group and the throttle chain that is applied to any requests sent by a
partner who belongs to this group.
• Which partners are authorized to invoke specific operations.

Authorization
The TIBCO API Exchange Gateway allows you to configure authorization policies
for partners that determine which partners’ requests are handled.
Authorization may be established in two ways:

TIBCO API Exchange Concepts

 Design Concepts 27
|

• By using an API key that is provided when the application developer registers
an application.
• By using an API and also authenticating with the partner using OAuth
authentication.

API Key
When using the first method (API key), the application must pass the API key
when calling an API function provided by the partner.

OAuth
If OAuth is configured, the application developer must use OAuth credentials,
and users may also be required to authenticate through an OAuth grant flow.

Caching
The TIBCO API Exchange Gateway provides a method for enabling caching,
including the use of caching agents.
Caching improves performance and reduces the load on back-end systems.

TIBCO API Exchange Concepts

28
| Chapter 3 API Gateway Concepts

TIBCO API Exchange Concepts

 | 29

Index

A
API Exchange Gateway 2
API Exchange Manager 2

C
customer support xiv

S
support, contacting xiv

T
technical support xiv
TIBCO Spotfire® 2
TIBCO_HOME xii

TIBCO <Product> <DocTitle>