TIBCO API Exchange Joomla Adapter User's Guide...1. Click Sign in at the top of the Getting Started page. 2. Click Create an account. 3. Fill out the form on the New API User Registration

Adapter Code for TIBCO® API Exchange and Joomla!

User’s Guide

Software Release 2.3September 2016

| iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viAdapter Code for TIBCO® API Exchange and Joomla! Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . viOther Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

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

Product Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Role of Application Developers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2What is an API Key?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Creating an Application to use API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Chapter 2 Developing an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Browsing the Featured Products of Getting Started Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Registering as an API User without User Name for Developer Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Resetting Your Password from Getting Started Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Browsing the Product Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Exploring a Product’s API Set with a Specified Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Requesting a Subscription. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Viewing Subscriptions and Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Commenting on a Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Registering an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Browsing the Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Editing an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Using the Application Dashboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Requesting an Replacement Key for an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

How to Use the Application Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Testing API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Building an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25What Is an API Key? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25How Do I Use an API Key in an API Call? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Contacting Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Copyright © 2016 TIBCO Software Inc. ALL RIGHTS RESERVED

iv | Contents


| v

Preface

Adapter Code for TIBCO® API Exchange and Joomla! enables the creation of Joomla!-based API Developer Portals with TIBCO® API Exchange to provide a highly branded and customizable experience to application developers and API providers.

Topics

• Related Documentation

Copyright © 2016 TIBCO Software Inc. ALL RIGHTS RESERVED.

vi | Related Documentation

Related Documentation

This section lists documentation resources you might find useful.

Adapter Code for TIBCO® API Exchange and Joomla! Documentation

The document set for Adapter Code for TIBCO API Exchange and Joomla! includes:

• Adapter Code for TIBCO® API Exchange and Joomla! Installation

• Adapter Code for TIBCO® API Exchange and Joomla! User's Guide

• Adapter Code for TIBCO® API Exchange and Joomla! Administration

• Release Notes for TIBCO® API Exchange and Joomla! 2.3.0

Other Product Documentation

You might find it useful to read the following documentation for other products:

• TIBCO® API Exchange - See http://docs.tibco.com

• Joomla! - See http://docs.joomla.org

Copyright © 2016 TIBCO Software Inc. ALL RIGHTS RESERVED.

http://docs.tibco.com

http://docs.joomla.org

| 1

Chapter 1 Overview

You can create an application using the Developer Portal that the Adapter Code for TIBCO API Exchange and Joomla! enables.

Topics

• Product Overview, page 2


2 | Chapter 1 Overview

Product Overview

TIBCO® API Exchange Manager allows service providers to package and offer services or APIs to developers inside or outside their company. A self-service portal enables developers to search and browse available APIs and documentation, request access, register applications, generate developer keys, and test API functionality.

If you have installed the Adapter Code for TIBCO® API Exchange and Joomla! component of TIBCO® API Exchange, you can use the Developer Portal that is provided with the component.

Role of Application Developers

As an application developer, you can perform the following activities:

• Browse through a product catalog, such as packages of APIs.

• Register for an account.

• Create applications and generate API keys.

• Request access to offered or custom product plans, such as subscriptions.

What is an API Key?

An API key is used to identify who is calling an API for authorization and tracing purposes. It is typically passed in through an HTTP header, a URI parameter, or through an OAuth grant flow.

To generate a key, a developer registers an application through the portal. The application typically represents a specific client that is calling or consuming the API. A client could be a TIBCO BusinessWorks™ process, a Java-based web application running in a web server, a JavaScript client running in a browser, or a native mobile application running on a tablet.

Creating an Application to use API

1. Create an application through the portal and requests an API key.

2. Request access to one or more products and plans.

3. Test the API and API key through the API Explorer.

4. Use the API key in calls to the API from their programming language of choice.


| 3

Chapter 2 Developing an Application

As an application developer, you can utilize self-service registration of users, create applications, explore APIs, and request subscriptions or request additional keys for applications.

Topics

• Getting Started, page 4

• Browsing the Product Catalog, page 7

• Exploring a Product’s API Set with a Specified Product, page 9

• Requesting a Subscription, page 11

• Viewing Subscriptions and Requests, page 13

• Commenting on a Product, page 15

• Registering an Application, page 16

• Browsing the Applications, page 18

• Editing an Application, page 19

• Using the Application Dashboard, page 20

• Requesting an Replacement Key for an Application, page 21

• How to Use the Application Key, page 22

• Testing API Operations, page 23

• Building an Application, page 25

• Contacting Support, page 26


4 | Chapter 2 Developing an Application

Getting Started

To develop an application using the Developer Portal, you can create applications, add products and associated APIs to the application, and request a product key for the application.

Before you decide to develop an application, you can browse through products that have been created by manager with the Developer Portal.

To access the Getting Started page for the Developer Portal, link to the URL where the port is installed; for example:

http://<hostname>/index.php

The Getting Started page appears:

Browsing the Featured Products of Getting Started Page

1. Click the left and right arrows next to the Featured Products list to browse the products.

2. Click on a featured product to view its product page.


Getting Started | 5

The product page for the selected product appears. The following figure shows the product page for a book catalog product.

From the Products page, you can perform the following tasks:

• View the plans provided for using the product.

• Explore the APIs the product provides.

• View documentation for the product.

3. To view a product plan, you must sign into the Developer Portal. Click the Sign-in selection in a product plan box.

If you do not have a user name, you can request one by registering as an API User. See the Registering as an API User section.

4. To view the APIs associated with the product, click the API Explorer tab.

5. To view the documentation for the product, click the Documentation tab.



Registering as an API User without User Name for Developer Portal

1. Click Sign in at the top of the Getting Started page.

2. Click Create an account.

3. Fill out the form on the New API User Registration page.

4. In the Validate field, enter the code that you see next to the field.

5. Select the check box next to I agree to the terms of use.

6. Click Register.

You will receive an e-mail informing you that you have been registered as a new user and that you need to activate your account.

7. Click on the activation link in the email to activate your account.

8. You are prompted to change your password.

9. Change your password and click Submit.

You can now log into the Developer Portal using the new password.

Resetting Your Password from Getting Started Page

1. Sign in to the Developer Portal.

2. Click on your Username, next to the Sign in link at the upper right of the Getting Started page.

An information page for your User ID appears.

3. Click the tools icon and from the pull-down menu, choose Edit.

The Edit User Profile page appears.

4. Enter your new password in the Password field and confirm it in the Confirm Password field.

5. Click Save to save the new password.


Browsing the Product Catalog | 7

Browsing the Product Catalog

1. Log into the Developer Portal.

2. Click the Products tab.

A list of available products appears. Products can be grouped in two ways:

— By Reference Data

— By Market Analysis Data

3. Click on a product.

The product page appears and the Plans tab is active. This tab shows the existing plans for the product, as shown in the following figure.

4. To request a subscription for the product, click Request Subscription in one of the product plans.

For detailed information on requesting a subscription, see the Requesting a Subscription section.

5. If the product includes REST APIS, to explore the APIs available for the product, click the API Explorer tab.

For detailed information on exploring the APIs for a product plan, see the Exploring a Product’s API Set section.

6. To view documentation about the product, click the Documentation tab.



A description of the product appears, including a description of the API set. A list of any documents that have been provided for the product also appears.


Exploring a Product’s API Set with a Specified Product | 9

Exploring a Product’s API Set with a Specified Product

If a product has REST APIs associated with it, you can use the API Explorer tab to explore the APIs in the product’s API set.

1. Click the Products tab.

2. Select a product in the display of products.

3. Click the API Explorer tab.

4. Click the down arrow in the field to the left of API Key, and from the pull-down list of applications, select an application.

For example, select the Librarian application.

The Developer Portal displays a list of the APIs associated with the product.

5. To view the operations available for an API, click an API name.

For example, click the Books API.

The operations associated appear. The following figure shows the operations for a Books API.



To the right of the API name there is a row of selections that lets you explore the API in more depth:

— Show/Hide Click Show/Hide to toggle the display of API operations on and off.

— List Operations Displays a list of operations for the API.

— Expand Operations Expands the list of operations and presents an interface that allows you to test the operations.

For information on testing API operations, see the Testing API Operations section.

— Raw Displays the API code as a text file (without formatting).

To view the documentation for the product, click the Documentation tab.


Requesting a Subscription | 11

Requesting a Subscription

1. Go to the Getting Started page.


3. Click on a product in the list of Featured Products.

A group of product plans appears.

4. To request a subscription, click Request Subscription in the plan display.

A dialog appears asking you to confirm the plan and your contact details.

5. Review the information on the confirmation dialog.

6. Select the I agree to the product-specific terms and conditions check box.

7. If you want to receive an email when the request is approved, select the check box that requests email confirmation.

8. Enter any notes or comments that you want to send to the administrator.

9. Click Confirm.

A subscription request is sent to the host administrator for your organization.



If your plan is an auto-subscribed plan, it does not need to go through the request and approve process. Once you request for a subscription, the subscription is created immediately for that organization.

If your plan is a non-auto-subscribed plan, it will need to go through the request work flow.

If your plan is a custom plan, you will need to request a subscription and provide the details, such as rate limit and quota limit for the subscription. After you input these details, this will need to go through the request work flow.


Viewing Subscriptions and Requests | 13

Viewing Subscriptions and Requests

From the Developer Portal you can view your subscriptions to products and your subscription requests.

1. Click the Subscriptions tab.

The subscriptions page appears. The Request tab is active:

The Requests page shows your requests for subscriptions to products, and indicates the status of the request.

2. To view your current subscriptions, click Subscriptions.

The Subscriptions page appears.



The Subscriptions page shows your existing subscriptions..

For the auto-subscribed plans, it does not need to go through the request and approve process, once you request for a subscription. The subscription is created immediately for that organization.

For non-auto-subscribed plans, it needs to go through the request work flow.

For custom plans, you will need to request a subscription and provide the details such as the rate and quota limit for the subscription. This then goes through the request work flow.


Commenting on a Product | 15

Commenting on a Product

When you are viewing a product on the Products page, if the system administrator has enabled comments, you can comment on a product.

To enter a comment, scroll down to the "Comments" section of the products page, and enter your comment in the comments area. The comments area shows a chain of comments regarding the product.



Registering an Application

Product managers can register applications and assign products to the applications.


2. Click the Applications tab.

3. Click Register Application.

An interface appears for defining the application.

4. Specify the following information to identify the application:

— Application name Enter a name for the application.

— Icon Optionally, associate an icon with your application by clicking Choose file, browsing for the file containing the image that you want, and then clicking Open.

The selected image appears on the configuration interface.

— Description Optionally, enter a description for the application.

The bottom of the Register New Application page shows the products that you can associate with the application.

5. To choose a product, complete these steps:

a. In the list of products, click on the name of a product.

A list of plans that have been enabled for the product appears.

b. To enable a plan, click Use (in the Enabled column).

A check box appears in the Enabled column.

If your system administrator has enabled OAuth authentication for your environment, and you want to use OAuth, click Yes in the OAuth section.


Registering an Application | 17

6. If you clicked Yes to specify OAuth authentication, complete these steps to apply scopes:

a. Click Choose.

b. In the Choose dialog window, select one or more scopes to apply and then click Apply.

c. If you are using Authorization Code Flow, then in the Redirect URL field, enter a URL that users will be redirected to when accessing the application.

Users might be prompted to enter a user ID and password to access a partner service referenced by the redirect URL.

d. If you want to specify additional redirect URLs and labels, click Add URL to display additional fields for specifying redirect URLs and labels.

You can specify up to ten redirect URLs.

7. Click Save to save your application.

An Applications window for your application appears. From this window you can request an application key for the application.

When you call an API associated with a product that has been assigned to your application, you must specify the application key in order to invoke the API.

8. Click Request Key.

An application key is generated and appears in the API Key field.

For information on how to use the application key, see the How to Use the Application Key section.



Browsing the Applications

By clicking the Applications tab, you can browse a list of the current applications and view the configurations for the applications.


2. A list of the current applications that you own appears.

You can search the list by entering a search string in Search Applications field. From the pull-down menu, you can choose to sort by Time created, Time Modified, or Title.

3. Click an application to view.

A page appears summarizing details of the application, in which you can perform the following activities:

— Click the name of a product that includes the application to view the plans available for the product and application.

— Click Request Key to request a new key for the application.

— Click Re-Sync to re-synchronize the Developer Portal with the API Exchange gateway.

— Click Edit to edit the application.

— Click the tools icon and from the pull-down menu, choose to edit the application or archive it.


Editing an Application | 19

Editing an Application

1. Sign into the Developer Portal.


3. Choose an application.

The Applications dialog for the application appears.

4. Click Edit.

5. Edit the configuration for the application as required.

For information on the fields for configuring the application, see the Registering an Application section.



Using the Application Dashboard

The Developer Portal provides an application dashboard, in which you can view the following features:

• Quota usage for the applications defined for the installation

• Quota threshold alerts

• Information on subscribed products

• Statistics by application or by product

• Contact information for members of organizations that own applications

1. Click the Dashboard tab.

The Application Dashboard appears.

You can toggle display of the dashboard sections by clicking on the section title. For example, to toggle display of application quota usage on or off, click Applications.

2. To view application quota usage, click Applications (if application quota usage is not already active).

A list of applications with quota usage information appears, as shown in the following figure.

— The bar graph for usage indicates the percent utilization of the usage quota. If the usage is over its configured threshold, the bar is red.


Requesting an Replacement Key for an Application | 21

Requesting an Replacement Key for an Application

In some situations, you might need to request a replacement key for an application. This might be necessary if an existing key has been compromised. When you obtain a replacement key for an application, the original key is disabled and the replacement key is enabled.



3. Click Request Key.

A prompt appears informing you that the existing key will be disabled.

4. To continue with generation of a new key, click OK.

A new key is generated and appears in the API key field.



How to Use the Application Key

You can use the application key in several areas of the developer portal interface. Some of these features include:

• Selecting the API Explorer and then specify an application key. This brings up a list of APIs that you can use with your application.

• Using the application key in the process of triggering analytics. In order to run analytics, your installation must be running TIBCO Spotfire, and Spotfire must be configured correctly.


Testing API Operations | 23

Testing API Operations

With the API Explorer interface, you can test operations in the APIs that comprise your applications.

1. Click the Products tab and choose a product.

2. Click the API Explorer tab.

3. Choose an API listed for the product.

4. Click Expand Operations.

The Developer Portal displays each operation in the API and a dialog that allows you to enter a test input for the operation. For example, the Books API includes a GET

Books/BookOperations/Author/{Author} operation. The following figure shows the dialog for the GET Books/BookOperations/Author/{Author} operation.

5. To test an operation, enter a value in the input field, and then click Try it out.

The Developer Portal runs the operation and either returns the requested record or displays an error code.

6. To close the expanded operation display, click on the name of the operation.



For example, to close the display for the Find Book by Author operation, click on Find Book by Author.


Building an Application | 25

Building an Application

After you have assembled products into an application, you must take certain steps to use the product key in your calls to APIs.

This section provides information on how to use the API key in application development.

What Is an API Key?

An API key is an opaque token passed as an HTTP header or as a URL parameter with each request.

How Do I Use an API Key in an API Call?

Specify the API key with the key APIkey or as a query parameter, as shown in the following example:

https://api.books.co/Books/Now?apikey=195-532d7700-44fe-9175-3a9d408a7286



Contacting Support

To contact customer support for the Developer Portal, click the Support tab, type a query, and then click Send your query.


Documents

TIBCO API Exchange Joomla Adapter User's Guide...1. Click Sign in at the top of the Getting Started page. 2. Click Create an account. 3. Fill out the form on the New API User Registration