TIBCO API Exchange Concepts

Transcription

1 TIBCO API Exchange Concepts Software Release 2.0 November 2013 Two-Second Advantage

2 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

3 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 TIBCO API Exchange Overview Overview Product Components Chapter 2 API Management Concepts What is an API? APIs as Products Partner Identity and Authentication API Key OAuth Applications Partner Authorization and Subscriptions User Management Functional Overview API Explorer Chapter 3 API Gateway Concepts Gateway Overview Cluster Gateway Functional Overview Design Time Components Run-Time Components

4 iv Gateway Operational Layer Gateway Management Layer Analytics Layer Design Concepts Facade Service Router Message Processing Life Cycle Mappings and Transformations Throttle Policies Routing Message Exchange Patterns Orchestration Partners Authorization Caching Index

5 Figures v Figures Figure 1 Entity Relationship for Products, Plans, Subscriptions, and Applications Figure 2 Functional Diagram of API Management Figure 3 Gateway Cluster Figure 4 Facade Service and Target Services

6 vi Figures

7 Tables vii Tables Table 1 General Typographical Conventions xii

8 viii Tables

9 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

10 x Related Documentation Related Documentation This section lists documentation resources you may find useful. TIBCO API Exchange Documentation The TIBCO API Exchange Documentation contains: 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.

11 Preface xi Other Documentation You might find it useful to read the documentation for the following: Joomla! - See Example project hosted on GitHub: Adapter Code for TIBCO API Exchange and Joomla!. See

12 xii Typographical Conventions Typographical Conventions The following typographical conventions are used in this manual. Table 1 General Typographical Conventions Convention ENV_NAME TIBCO_HOME <ProductAcron ym>_home Use TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other installation environments. Incompatible products and multiple instances of the same product must be installed into different installation environments. 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 font Bold code font is used in the following ways: 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]

13 Preface xiii Table 1 General Typographical Conventions (Cont d) Convention italic font Key combinations Use 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 name separated by a plus sign indicate keys pressed simultaneously. For 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.

14 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 How to Access TIBCO Documentation You can access TIBCO documentation here: 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: If you already have a valid maintenance or support contract, visit this site: Entry to this site requires a user name and password. If you do not have a user name, you can request one.

15 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 Overview, page 3

16 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

17 Overview 3 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.

18 4 Chapter 1 Concepts Overview

19 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

20 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) 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).

21 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.

22 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, 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.

23 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.

24 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

25 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.

26 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

27 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.

28 14 Chapter 2 API Management Concepts

29 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

30 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

31 Gateway Overview 17 Throttle Management Routing Cache management Transformation and orchestration Logging and statistics

32 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.

33 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.

34 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.

35 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.

36 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.

37 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:

38 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

39 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.

40 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:

41 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.

42 28 Chapter 3 API Gateway Concepts

43 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>