TIBCO Mashery

(1)

TIBCO Mashery

^®

Local 3.1.1

Installation and Configuration Guide

August 2016

www.mashery.com

(2)

Mashery^® Local Installation and Configuration Guide 2

Copyright Notice

© 2016 TIBCO Mashery™ All rights reserved.

This help system and the accompanying software it describes are copyrighted with all rights reserved. Under U.S. and international copyright laws, neither this help system nor the software may be copied or reproduced, in whole or in part, in any form, and no part of this system or the software may be stored in a retrieval system, electronic or mechanical, without the written consent of Mashery®, except in the normal use of the software or to make a backup copy.

Mashery® software is provided under a written agreement and may be used or reproduced only in accordance with the terms of that agreement. It is against the law to reproduce Mashery®

software on tape, disk, or any other medium for any purpose other than the licensee’s expressly authorized use.

Trademarks

TIBCO and TIBCO Mashery are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

Mashery, Inc.

575 Market Street, 15th Floor San Francisco, CA 94105

Part Number: IO-Docs-cfg-04-2012

(3)

Chapter 1 About this Guide

Introduction

This guide describes how to install and configure Mashery^® Local. Mashery^® Local is an on premise traffic manager in a virtual appliance that manages and runs your API-related network traffic behind your firewall for enhanced API response time and security. Mashery^® Local securely interacts with the Mashery^® Cloud hosted Developer Portal, Administration Dashboard and API Reporting and Analytics modules.

Assumptions

This guide assumes that you are using VMware ESX servers with the vSphere client on Microsoft Windows. If you have an internal cloud, established best practices will be applied (for example disk alignment). If you are using different servers and clients, the underlying concepts implied by the installation and configuration steps still apply.

Chapter Overview

The Mashery^® Local Installation and Configuration Guide is divided into the following chapters:

 Chapter 2. Prerequisites and Installation Overview - Provides you with a quick reference on software requirements and summarizes the installation process.

 Chapter 3. Installing and Configuring Mashery^® Local - Describes how to install and configure Mashery^® Local Master and Slave virtual machine instances, and how to configure the Load Balancer.

 Chapter 4. Advanced Configuration and Maintenance - Describes how to enable

notifications, LDAP, and API and JMX reporting access. Also describes how to locate and install updates.

 Chapter 5. Using the Adapter SDK - Describes how to use the adapter SDK to create and deploy custom processors.

 Chapter 6. Testing the New Instance - Describes how to test your Mashery^® Local instance.

 Chapter 7. Troubleshooting Guide - Describes how to use the troubleshooting tools.

(6)

About this Guide

Conventions

This guide uses the following conventions:

 Keys you press simultaneously appear with a plus (+) sign between them (for example, Ctrl+P means press the Ctrl key first, and while holding it down, press the P key).

 Field, list, folder, window, and dialog box names have initial caps (for example, City, State).

 Tab names are bold and have initial caps (for example, People tab).

 Names of buttons and keys that you press on your keyboard are in bold and have initial caps (for example, Cancel, OK, Enter, Y).

(7)

Chapter 2 Prerequisites and Installation Overview

Deployment Topology

The following diagram depicts a typical deployment topology for Mashery^® Local:

Hardware and Software Requirements

The following table lists the hardware and software requirements for Mashery^® Local.

Requirement Description

Server ^ Must have VMware ESX/ESXi (4.x or greater) installed, configured and running.

 Must have at minimum 2GB of RAM and 50GB of disk space per VM Instance.

(8)

Prerequisites and Installation Overview

Requirement Description

 Must have 1 Gbps Network connection.

Windows Client  Must have VMware vSphere client (4.x or greater) installed.

 Must have 1 Gbps Network connection to Server.

 Must be routable to from upstream network equipment such as load balancers, firewalls, or routers.

Mashery^® Local Virtual

Appliance

Minimum Requirements:

 1 virtual CPU

 1.7GB RAM

 50GB hard drive space

 2 Virtual Network Interfaces (External eth0/Internal eth1). See the best practice recommendation in step 12 on page 16 regarding recommended roles for eth0 and eth1.

 For automatic configuration, both network interfaces must have DHCP running on them.

Note: You can also configure the IP address manually by logging in via the console, editing /etc/sysconfig/network- scripts/ifcfg-eth0, editing /etc/sysconfig/network-

scripts/ifcfg-eth1, and then performing a service network restart.

 Masters and Slave must all be on the same virtual network on the internal interface.

Note: It is not recommended to run both the master and slave nodes in the same ESX host. In addition to availability issues, there are some processes with high IO usage that can cause temporary performance impacts for all VMs on the host.

Registering a new slave node causes a performance impact on all nodes running on the same VM host. This is because there is a fortnightly database backup that impacts

performance of the master node and any slaves on the same VM host. The performance impact exists for this operation, even when the master and slave nodes are on separate VM hosts.

 Built for ESX 4.X and HW level 7. VMware limitations and supported hardware and software for this build include:

o Limitations: 255 GB memory, 8 processors, 10 network adapters

o Supported hardware and software: ESX/ESXi 4.x, vCenter 4.x, vCloud Director 1.0, Server 2.0, Workstation 6.5.x,

Workstation 7.x

(9)

Prerequisites and Installation Overview

Requirement Description Web Console

Configuration

 Must have IE 8 or later, Chrome, Safari, or Firefox to perform the web console configuration on the Mashery^® Cluster Manager UI within Mashery^® Local.

 Necessary services and API keys have been configured in your Developer Administration Dashboard. Necessary services and API keys include service definitions in the API Settings area of the product and then the API Keys for developers to make API calls.

Service definitions for Mashery^® define the API endpoints. The keys give you access to the endpoints.

 Mashery^® Client Service Management (CSM) must have enabled your service to include Mashery^® Local and provided you a Cloud Key and Secret. For more information, contact TIBCO Support.

VMI Bundle from Mashery^®

 Mashery^® CSM has provided the Mashery^® Local download link.

Overview of Installation and Configuration Process

This section provides a roadmap of the installation process for Mashery^® Local:

1. Follow the instructions provided in this chapter to ensure that you have adequately addressed the minimum hardware and software requirements, and installed the prerequisite software.

2. Deploy the Mashery^® Local VMI bundle (OVF Template) as described in Deploying the Mashery^® Local OVF Template.

3. Configure a Mashery^® Local Master as described in Configuring a Mashery^® Local Master.

4. Configure Slave(s) to the Mashery^® Local Master as described in Configuring Slave(s) to the Master. It is best practice to set up production with no less than 2 Slaves per Master.

5. Configure the load balancer as described in Configuring the Load Balancer.

6. Perform advanced configuration such as enabling notifications, LDAP, and API and JMX reporting access as described in Advanced Configuration.

(10)

Chapter 3 Installing and Configuring Mashery ^® Local

Deploying the Mashery

^®

Local OVF Template

To deploy the Mashery^® Local OVF Template:

1. Start the vSphere Client application on a computer that has access to the target ESX server.

2. Select File>Deploy OVF Template.

The vSphere Source window appears.

3. Navigate to and select the .ova file you received from Mashery^®.

(11)

Installing and Configuring Mashery® Local

Note: To complete this step, you will need to have previously downloaded the OVA file and stored it in a location that is accessible to the computer running vSphere.

vSphere displays the OVF template’s details. For Mashery^® Local 3.1.1, the details are as follows:

 Version: 3.1.1.0

 Download size: 877.4 MB

 Size on disk: 2.2 GB (thin provisioned), 50 GB (thick provisioned)

(12)

4. Click Next.

The End User License Agreement appears.

5. Read and accept the End User License Agreement and click Next.

The vSphere Name and Location window appears.

6. Enter a name that is meaningful to your managing your virtual environment. This name has no relevance to what your users and partners will see in Mashery^® products but is meaningful to your administration of your ESX environment. Your operations team likely has naming conventions that should be followed. Then, click Next.

(13)

The Datastore window appears.

7. Select the appropriate VM datastore, and then click Next.

Note: Ensure that you pick a datastore with enough free space. See Hardware and Software Requirements for guidance.

The Disk Format window appears.

(14)

8. Select the Thin provisioned format or Thick provisioned format option for Disk Format according to your needs and best practices, and then click Next. See this VMware performance study for guidance. Thin clients, although faster, need to be

monitored closely to ensure you do not run out of space and sometimes require attention to shrink them back down. Remember also that a large number of thin provisioned VMs can affect performance due to frequent metadata updates.

The Network Mapping window appears.

9. Select the appropriate Network Mapping for your environment, and then click Next.

(15)

The Ready to Complete window appears.

10. Click Finish to complete the provisioning.

The vSphere Client reports as follows when the deployment is complete. Click Finish.

(16)

11. Select the “Power On” icon for the instance to boot the instance.

12. You need to get the IP addresses of the instance for use when performing further configuration steps within the Mashery^® Local appliance. Select the instance and then click View All as shown below to find the IP address and make a note of them.

(17)

A recommended best practice is to select IP addresses as follows:

 eth0: use as a public interface where API calls would be coming in from the developers.

 eth1: use as an internal interface for the nodes to talk to each other and where nodes can interface with the backend systems.

This scheme allows you to deal with your firewall rules more easily and keep services on different subnets if needed for security reasons. Typically, the Admin UI would be handled via eth1 as it most likely would be from the internal subnet. The Slave would also be connecting to the Master on eth1 as it is internal traffic.

You are now ready to configure the Mashery^® Local instance. You may optionally create a number of slave instances before proceeding by repeating steps 1-12 above for each.

Configuring the Mashery

^®

Local Cluster

Mashery^® Local may run configured in a cluster of one master and multiple slaves. To configure the Mashery^® Local cluster, you need to:

 Configure a Mashery^® local master

 Configure slave(s) to the local master

Configuring a Mashery

^®

Local Master

To configure a Mashery^® Local master:

1. Browse to the Mashery^® Local Cluster Manager of the master by using the IP address of the instance that you found in step 12 above:

https://<IP_address_of_master>:5480

(18)

2. Login with username administrator and the password provided by Mashery^®. Click Master.

The Configure Master window appears.

Enter an instance name (this name may be equal or different from the name you

provided VMware and will eventually display in the Mashery^® Admin Dashboard) that is meaningful to your operation, the Mashery^® Cloud Key and shared secret provided by Mashery^®, and the NTP server address, if used.

(19)

3. Click Commence Initiation Sequence.

After the Master initializes with the Mashery^® cloud service, a completion page appears.

4. Click Continue.

5. Navigate to the Cloud Sync page and perform manual syncs for API Settings, Developers, and OAuth Tokens by clicking the adjacent icons:

(20)

6. Test the instance as described in Chapter6.

7. See the instructions in Chapter 4. Advanced Configuration for how to enable notifications, LDAP, and API and JMX reporting access if desired.

Configuring Slave(s) to the Master

To configure Slave(s) to the master:

1. Browse to the Mashery^® Local Cluster Manager of the slave by using the IP address of the instance that you found in step 12 above:

https://<IP_address_of_master>:5480

2. Login with username administrator and the password provided by Mashery^®. 3. Click Slave.

(21)

4. Enter an instance name (this name may be equal or different from the name you

provided VMware and will eventually display in the Mashery^® Admin Dashboard) that is meaningful to your operation, the Master Instance IP, the Mashery^® Cloud Key and shared secret provided by Mashery^®, and the NTP server address, if used.

(22)

5. Click Register with Mashery and Master.

6. Click Continue.

7. Test the instance as described in Chapter6.

8. See the instructions in Chapter 4. Advanced Configuration for how to enable notifications, LDAP, and API and JMX reporting access if desired.

Configuring the Load Balancer

Mashery^® recommends using a Load Balancer to best utilize the cluster, although this is not required because you may route your API traffic directly to each instance.

Each instance hosts a service called /mashping. Configure the Load Balancer to access the following address, without the host header:

http://<IP_address_of_instance>/mashping

(23)

If the Load Balancer and the cluster is working correctly, /mashping returns the following response:

HTTP/1.1 200 OK

Server: Mashery Proxy

Content-Type: application/json; charset=UTF-8 Transfer-Encoding: chunked

{"status":200,"time":1315510300,"message":"success"}

If /mashping returns any other response, then the load balancer should remove the instance from the cluster and either retry after a period of time or alert operations to investigate.

Mashery^® Local has two instance types: Master and Slave. Should the Load Balancer pull the Master out of the cluster pool, an Operations engineer should immediately investigate whether it can be recovered, and, if not, promote a Slave to Master. If no Master exists in the pool, data synchronization with the Mashery^® Cloud Service will not occur with the

exception of API event activity. Access Tokens, Keys, Applications, Classes and Services will not be synchronized.

Configuring the Instance

The Instance Management tab allows you to configure additional settings for that particular instance. You can edit the instance name, configure instance settings, and update software and custom adapters. Additional system-level parameters can be tuned here such as

application memory allocation, configuration cache size, maximum concurrent connections, and connection pool size for the database.

To configure an instance:

1. On the Mashery Cluster Manager tab, click Instance Management.

2. Click the Management Options for which you want to configure the settings.

A text box is displayed for the selected Management Options.

(24)

3. Enter the details for the following fields to configure the instance.

(25)

Field Description

Use NTP (recommended) NTP server address.

Memory Allocation Specify application memory size as a fraction of the available memory.

Concurrent Connections Sets the maximum number of concurrent connections to the service instance.

Database Connector Sets the maximum number of concurrent connections the instance will make to its database.

Configuration Cache Specify the memory (in MB) to use for configuration cache.

Disable IPv6 Select this option to disable IPv6 if IPv6 traffic should not be allowed to the backend. By default, Mashery Local 3.1.1 supports both IPv4 and IPv6.

4. Click Save.

The instance is configured for the specified settings.

(26)

Chapter 4 Advanced Configuration and Maintenance

Chapter 3 described how to install and configure a basic environment complete with a master, slaves and load balancing. This chapter describes how you can extend your installation by adding the following capabilities:

 Quota Notifications

 LDAP Configuration

 API and JMX Reporting

This chapter also describes how to locate and install updates.

Configuring Quota Notifications

You can configure Mashery^® Local to send Over Throttle Limit, Over Quota Limit and Near Quota Limit Warning notifications when an API key exceeds or nears its limits.

To configure quota notifications, follow the instructions in the illustration below:

(27)

Advanced Configuration and Maintenance

Similar notifications settings are available on the slave instances as well.

Configuring LDAP

You can configure Mashery^® Local to be authenticated against your existing LDAP server and to include filters and objects.

To configure LDAP, follow the instructions in the illustration below:

(28)

 The User Object field allows you to specify what the user object is called on your LDAP server.

 The Record Filter field accepts a Pluggable Authentication Module (PAM) filter. This allows you to set a filter that checks for a specific attribute of the user object and deny login if the match fails.

Similar LDAP settings are available on the slave instances as well.

Configuring OAuth 2.0 API Access

Mashery^® Local provides a local OAuth 2.0 API. The API can be available on any computer within the cluster, regardless if the instance is a Master or Slave.

To configure and use the OAuth 2.0 API:

1. Turn on the OAuth 2.0 API by following the instructions in the screen shot below.

(29)

You need to enter a username and password to access the API using basic HTTP authentication.

2. Similar API settings are available on the slave instances as well. On all slave instances, navigate to Mashery Cluster Manager -> Account Settings, and under Mashery Local API Settings, select the Enable API Access check box.

Making OAuth 2.0 Calls

The Mashery^® Local OAuth 2.0 API is available over SSL on port 8083 of your local instance.

Authorization is handled via HTTP authentication using the credentials you specified in the steps above.

(30)

Sample Call

curl -v -d '{

"method":"oauth2.fetchApplication",

"id": "2",

"params":{

"service_key" : "<service_key>",

"client" : {"client_id":"<api_key>", "client_secret":"<api_secret>"}, "response_type" : null,

"uri" : {"redirect_uri": "http://sometest.test.com/error?key=foo", "state":"bar"}

}

}' 'https://<masherylocal_host>:8083/v2/json-rpc/' -u '<api_access_user>:

<api_access_password>' -k

For host name, the IP Address of the instance where the OAuth API is enabled can be used.

If the OAuth API on Mashery^® Local is to be used in conjunction with traffic outside the firewall, it is recommended that the Mashery^® Local cluster be fronted with a load balancer with a host name is associated with it (in addition to mapping port 8083 to an acceptable externally accessible port such as 443).

Understanding the OAuth 2.0 API

The complete technical documentation for the Mashery^® OAuth 2.0 API is available online at http://support.mashery.com/docs/read/mashery_api/20/OAuth_Supporting_Methods.

To see this documentation, request the access by contacting your client services contact.

The following table describes the API at a high level:

API Method Purpose

fetchApplication Used during the Authorization step when the service provider’s authorization server presents the resource owner with

information about the client requesting access to the resource owner’s data. The API calls is used to verify if the client is valid and fetches the client application data (name, attributes,

redirection url) which will be used to provide information to the end user.

createAuthorizationCode (Authz Code grant type only)

After the resource owner has successfully authenticated against the service provider’s authorization server and authorized the client, the authz server will make this API call to Mashery^® to generate the authz code which can be subsequently used to obtain an access token. As a part of this API call, the service provider will also supply the user-context (userid) for the authenticated user. The service provider returns the authz code to the client using the redirection url.

(31)

API Method Purpose

createAccessToken API call used to generate the access token.

 For the authz code grant type, a valid authz code must be presented.

 For implicit and resource owner grant types, this occurs after the resource owner has been authenticated (user- context should be supplied). Service provider initiates the API call.

 For Client Credentials flow, only the client credentials are verified.

 When exchanging a refresh token, a valid refresh token must be presented.

Note: Both client id and secret must be presented when requesting an access token except in the case of Implicit grant type.

fetchAccessToken May be used by the service provider to validate access tokens and may be used as an additional layer of security or when certain API calls are sent directly to the provider instead of through Mashery^®.

fetchUserApplications Used by the service provider to present the resource owner with the client applications that been authorized by that resource owner. This is typically used in the “Account” section of the service provider’s site where the resource owner can view the list.

revokeAccessToken Used by the service provider to allow the resource owner to revoke access to specific client applications that been authorized by that resource owner. This is typically used in the “Account”

section of the service provider’s site where the resource owner can view the list authorized applications and select which application should no longer be allowed access.

revokeUserApplication Revokes all tokens for an application for the specified user.

Configuring JMX Reporting Access

You can enable the JMX service to allow you to monitor Mashery^® Local using the Java Management Extension. In addition to the standard MBeans exposed by JMX, the list of Mashery^® specific components and metrics that are exposed are:

 Jetty: Metrics exposed are Connections, Open connections, Thread pool low threads, Thread pool max threads, Thread pool min threads, Thread pool spawn or shrink

 DB Connection Pools: Metrics exposed are Active Connections, Timeout

(32)

 Memcache Connection Pools: Metrics exposed are Active connections, Connection Timeout, Max Reconnect Delay

 HTTP Connection Pools: Metrics exposed are Number of connections To enable and configure the JMX Service:

1. Turn on the JMX service by following the instructions in the screen shot below.

You need to enter a username and password to access the service.

2. Download the server certificate to your local machine using the link provided on the same configuration screen:

3. On your local computer, import the certificate to a new trust store. Use an arbitrary trust store password; for example, trustpassword.

keytool -import -file ~/Downloads/mashery-proxy.cer -keystore mashery-proxy- jmxremote.jks

(33)

4. Launch JConsole with the newly created trust store.

jconsole -J-Djavax.net.ssl.trustStore=mashery-proxy-jmxremote.jks -J- Djavax.net.ssl.trustStorePassword=trustpassword

5. In JConsole, connect to the Mashery^® Local node to monitor by specifying its IP address (the second or private interface) and port 8084. Enter the credentials specified in the Admin console. For example 192.168.1.110:8084 apiuser/apipassword.

You should be successfully connected and able to monitor the node.

Installing Updates

To find and install updates, follow the instructions in the screen shot below:

Prerequisite: The ISO update image should be mounted in the URL.

1. On the Mashery Local page, click the Update tab.

The Status tab is selected by default.

2. Click Check Updates to check if the latest version of the appliance is available for installation.

Note: Install Updates is enabled only when a latest version of the appliance is available.

To update the Repository Settings, see Updating Repository Settings.

3. Click Install Updates.

The appliance installation starts on the Mashery^® Local Instance.

On completion of the process, the Process Completed message is displayed.

(34)

 If the appliance update is successful, the Appliance Version on the Update Status section is updated automatically to the latest version.

 If the appliance update fails, an error message is displayed in red.

Updating Repository Settings

To update the Repository Settings, follow the instructions in the screen shot below:

1. On the Update tab, click Settings.

The Settings page is displayed.

2. Click Use Specified Repository.

(35)

3. Enter the following details:

Field Description

Repository URL Repository URL is the URL on which the ISO is mounted in the settings table.

Username User name.

Password Password.

4. Click Save Settings.

The URL settings are saved.

(36)

Chapter 5 Using the Adapter SDK

This chapter outlines the development process for writing custom adapters using the Adapter SDK for Mashery^® Local Traffic Manager. This chapter provides the list of areas of extension provided in the SDK and code samples to illustrate the extension process.

Adapter SDK Package

The Adapter SDK defines the Traffic Manager domain model, tools and APIs and provides extension points to inject custom code in the processing of a call made to the Traffic Manager.

Note: DIY SDK adapters need to be coded and compiled using JDK 1.6 or lower.

The Adapter SDK package contains the following:

Mashery

^®

Domain SDK

Mashery^® Domain SDK packaged in com.mashery.trafficmanager.sdk identifies the traffic manager SDK and provides access to the Mashery^® domain model which includes key objects such as Members, Applications, Developer Classes, Keys, Packages

Mashery

^®

Infrastructure SDK

Mashery^® Infrastructure SDK provides the ability to handle infrastructure features and contains the following:

 Mashery^® HTTP Provider

The HTTP provider packaged as com.mashery.http provides HTTP Request/Response processing capability and tools to manipulate the HTTP Request, Response, their content and headers.

 Mashery^® Utility

The utility packaged as com.mashery.util provides utility code which handles frequently occurring logic such as string manipulations, caching, specialized collection handling, and logging.

(37)

Using the Adapter SDK

SDK Domain Model

The Traffic Manager domain model defines the elements of the Traffic Manager runtime.

The following table highlights some of the key elements:

Element Description Description

User A user or member subscribing to APIs

and accesses the APIs. com.mashery.trafficmanager

.model.User API An API represents the service definition.

A service definition has endpoints defined for it.

com.mashery.trafficmanager .model.API

Endpoint An Endpoint is a central resource of an API managed within Mashery^®. It is a collection of configuration options that defines the inbound and outbound URI's, rules, transformations, cache control, security, etc. of a unique pathway of your API.

An Endpoint is specialized as either an API Endpoint or a Plan Endpoint. This specialization provides context to whether or not the Endpoint is being used as part of a Plan or not.

 Generic endpoint entity representation:

com.mashery.trafficman ager.model.Endpoint

 API endpoint entity representation:

com.mashery.trafficman ager.model.APIEndpoint

 Plan endpoint entity representation:

com.mashery.trafficman ager.model.PlanEndpoint Method A method is a function that can be called

on an endpoint and represents the method currently being

accessed/requested from the API request.

A method could have rate and throttle limits specified on it to dictate the volume of calls made using a specific key to that method.

A Method is specialized as either an API Method or Plan Method. The

specialization provides context to whether or not the Method belong to a Plan.

 Generic method entity representation:

com.mashery.trafficman ager.model.Method

 API method entity representation:

com.mashery.trafficman ager.model.APIMethod

 Plan method entity representation:

com.mashery.trafficman ager.model.PlanMethod Package A Package is a mechanism to bundle or

group API capability allowing the API Manager to then offer these capabilities to customers/users based on various access levels and price points. A Package

represents a group of Plans.

com.mashery.trafficmanager .model.Package

Plan A Plan is a collection of API endpoints,

methods and response filters to group com.mashery.trafficmanager .model.Plan

(38)

Element Description Description

functionality so that API Product

Managers can manage access control and provide access to appropriate Plans to different users.

API Call The API Call object is the complete transaction of the incoming request received by the Traffic Manager and the outgoing response as processed by the Traffic Manager. It provides an entry point into all other entities used in the execution of the request.

com.mashery.trafficmanager .model.core.APICall

Key A key is an opaque string allowing a developer to access the API functionality.

A key has rate and throttle controls defined on it and dictates the volume of calls that can be made to the API by the caller.

A Key can be specialized as an API key or Package Key. This specialization provides context to whether the key provides access to an API or a specific Plan in a Package.

 Generic key entity representation:

com.mashery.trafficman ager.model.Key

 API key entity representation

com.mashery.trafficman ager.model.APIKey

 Package key entity representation:

com.mashery.trafficman ager.model.PackageKey Application An application is a developer artifact that

is registered by the developer when he subscribes to an API or a Package.

com.mashery.trafficmanager .model.Application

Rate Constraint

A Rate Constraint specifies how the amount of traffic is managed by limiting the number of calls per a time period (hours, days, months) that may be received.

com.mashery.trafficmanager .model.RateConstraint

Throttle

Constraint A Throttle Constraint specifies how the velocity of traffic is managed by limiting the number of calls per second that may be received.

com.mashery.trafficmanager .model.ThrottleConstraint

Customer Site A customer specific area configured through the developer portal.

com.mashery.trafficmanager .model.CustomerSite

(39)

Extended Attributes

The traffic manager model allows defining name-value pairs on different levels of the model.

The levels are identified here:

 Application

 Customer Site

 Key (both API Key and Package Key)

 Package

 Plan

 User

Pre and Post Processor Extension Points

This version of the SDK allows extensions for Processors only. This means that only pre and post processing of requests prior to invocation of the target host are allowed.

Listener Pattern

The extension API leverages a listener pattern to deliver callbacks to extension points to allow injecting custom logic.

A call made to the traffic manager is an invocation to a series of tasks. Each step in the workflow accomplishes a specific task to fulfill the call. The current API release only allows customization of the tasks prior to invoking the API server (pre-process) and post receipt of the response from the API server (post-process). The callback API handling these extensions is called a Processor.

The pre-process step allows a processor to receive a fully formed HTTP request targeted to the API server. The processor is allowed to alter the headers or the body of the request prior to the request being made to the server. Upon completion of the request and receiving the response the Traffic Manager allows the processor to alter the response content and headers prior to the response flowing back through a series of exit tasks out to the client.

Event types and Event

The transition of the call from one task to the next is triggered through ‘events’ and an event is delivered to any subscriber interested in receiving the event. The SDK supports two event- types which are delivered synchronously.

 Pre-Process Event type: This event is used to trigger any pre-process task.

 Post-Process Event type: This event is used to trigger any post-process task.

The subscribers in this case will be Processors registered in a specific manner with the Traffic Manager API.

(40)

Note: An event-type is a template realized as an Event during runtime.

Event Listener API

The Traffic Manager SDK provides the following interface and is implemented by custom processors to receive Processor Events.

package com.mashery.trafficmanager.event.listener;

import com.mashery.trafficmanager.event.model.TrafficEvent;

/*** Event listener interface which is implemented by listeners which wish to handle Traffic events. Traffic events will be delivered via this callback synchronously to handlers implementing the interface.

The implementers of this interface subscribe to events via annotations. E.g.

Processor events need to handle events by using annotations in the com.mashery.proxy.sdk.event.processor.annotation */

public interface TrafficEventListener {

/*** The event is delivered to this API @param event*/

void handleEvent(TrafficEvent event);

}

Implementing and Registering Processors

Writing custom processors involves the following general steps:

 Downloading the SDK

 Implementing the event listener

 Implement lifecycle callback handling

 Adding libraries to the classpath

The following sections describe these steps in more detail.

Downloading the SDK

To download the SDK:

1. Click Download SDK, as shown below:

(41)

2. Use your favorite IDE and put the SDK jars in your classpath.

3. Create a project and a new java class. The details of that process are skipped here and assumed that the developer will use the relevant IDE documentation to accomplish this.

Implementing the Event Listener

To implement the event listener:

1. Employ the Traffic Event Listener interface (introduced above in the section Event Listener API) as shown below:

package com.company.extension;

public class CustomProcessor implements TrafficEventListener{

public void handleEvent(TrafficEvent event){

//write your custom code here }

}

2. Annotate your code to ensure that the processor is identified correctly for callbacks on events related to the specific endpoints it is written to handle:

@ProcessorBean(enabled=true, name=”com.company.extension.CustomProcessor”, immediate=true)

public class CustomProcessor implements TrafficEventListener{

}

The annotation identifies the following properties

 enabled: Identifies if the processor is to be enabled

 name: Identifies the unique name of the processor as configured in API Settings (see marked area in ‘red’ below)

(42)

 immediate: Identifies if the processor is enabled immediately

Note that the name used in the annotation for the Processor MUST be the same as configured on the portal for the Endpoint>Pre/Post Processing, shown below:

Implementing lifecycle callback handling

If you wish to have some initialization work done once and only once for each of the processors, then implement the following interface:

package com.mashery.trafficmanager.event.listener;

/*** The lifecycle callback which gets called when the processor gets loaded when installed and released*/

public interface ListenerLifeCycle {

/*** The method is called once in the life-cycle of the processor before the processor is deemed ready to handle requests. If the processor throws an exception, the activation is assumed to be a failure and the processor will not receive any requests @throws ListenerLifeCycleException*/

public void onLoad(LifeCycleContext ctx) throws ListenerLifeCycleException;

/*** The method is called once in the life-cycle of the processor before the processor is removed due. The processor will not receive any requests upon inactivation.*/

public void onUnLoad(LifeCycleContext ctx);

}

The onLoad call is made once prior to the processor handling any requests and onUnLoad

(43)

call is made before the processor is decommissioned and no more requests are routed to it.

The lifecycle listener can be implemented on the Processor class or on a separate class. The annotation needs to add a reference to the lifecycle-class if the interface is implemented (see highlighted property in red below).

@ProcessorBean(enabled=true, name=”com.company.extension.CustomProcessor”, immediate=true, lifeCycleClass=”com.company.extension.CustomProcessor”)

public class CustomProcessor implements TrafficEventListener, ListenerLifeCycle{

public void onLoad(LifeCycleContext ctx) throws ListenerLifeCycleException{

}

public void onUnLoad(LifeCycleContext ctx){

} }

Note: The lifeCycleClass property should point to the class implementing the Listener LifeCycle interface. This also allows having a separate lifecycle listener interface as follows (note the different lifeCycleClass name).

The example below shows a different class implementing the Life Cycle callback:

@ProcessorBean(enabled=true, name=”com.company.extension.CustomProcessor”, immediate=true, lifeCycleClass=”com.company.extension.CustomProcessorLifeCycle”) public class CustomProcessor implements TrafficEventListener {

}

} }

public class CustomProcessorLifeCycle implements ListenerLifeCycle{

}

} }

(44)

Adding Libraries to Classpath

If the processor needs third-party libraries, those can be used in development and packaged with the processors as described in the next section.

Deploying Processors to Runtime

Deploying a custom processor involves the following general steps:

 Packaging the custom processor

 Uploading the custom processor

 Enabling Debugging

The following sections describe these steps in more detail.

Packaging the Custom Processor

Once the processor code is written, compile the classes and create a jar file with all the classes. Any third party libraries used must be specified in the Manifest.MF of the jar containing the processor classes.

The classpath entries are introduced as follows. For example, if you want to add apache- commons.jar, then you would add it as follows to the META-INF/MANIFEST.MF file of the jar:

Class-Path: apache-commons.jar

Uploading the Custom Processor

To upload the custom processor:

1. Once the jar file is created, add it to a ZIP file.

Upload the ZIP file to the Mashery^® Local instance by using the Mashery^® Local Admin UI as shown below:

(45)

If the upload is successful, a message appears that the adapters were uploaded successfully.

(46)

Enabling Debugging

During development, it is sometimes necessary to enable debugging on the Mashery^® Local instance.

To enable debugging, click the Enable debugging check box, indicate the port number to which you will connect your debugger, and then click Save:

Caching Content

The custom endpoints can cache content during the call handling. The cache configuration is found in the section Manage Custom Content Cache on the API Settings page, shown below highlighted with a red box:

(47)

Manage Custom Content Cache provides the following options:

 Custom TTL: A default TTL provided for the cache

 Update TTL: Provides ability to save any TTL changes

 Update TTL and Flush Cache: Update the database with the updated TTL and flush the cache contents

 Flush Cache: Allow the cache contents to be flushed

(48)

The SDK provides references to a Cache where all this data is stored. The cache interface provided in the callback to the TrafficEventListener is:

package com.mashery.trafficmanager.cache;

/*** Cache API which allows extensions to store and retrieve data from cache*/

public interface Cache { /**

* Retrieves the value from the cache for the given key * @param key

* @return

* @throws CacheException */

Object get(String key) throws CacheException;

/**

* Puts the value against the key in the cache for a given ttl * @param key

* @param value * @param ttl

* @throws CacheException */

void put(String key, Object value, int ttl) throws CacheException;

}

A reference to the cache can be found on the ProcessorEvent which is reported on the callback. Here is an example of how to access cache on callback:

@ProcessorBean(enabled=true, name=”com.company.extension.CustomProcessor”, immediate=true

public class CustomProcessor implements TrafficEventListener, ListenerLifeCycle{

ProcessorEvent processorEvent = (ProcessorEvent) event;

Cache cacheReference = processorEvent.getCache();

//Add data to cache try{

cacheReference.put(“testkey”, “testValue”, 10) }catch(CacheException e){

//load data or load default data }

//write your custom processor code here }

}

(49)

A reference to cache is also available on the lifecycle callback:

public class CustomProcessorLifeCycle implements ListenerLifeCycle{

Cache cache = ctx.getCache();

// perform cache operations }

} }

(50)

Chapter 6 Testing the New Instance

You should test a new instance after installing and creating it.

To test the new instance

One approach to test a new instance is:

1. Find the API you wish to test in the API Settings area of the Mashery^® Admin Dashboard and identify an associated endpoint that is ready for testing.

2. Create a test API key for the API identified in the previous step. You accomplish this in the Users area accessed by clicking the Users tab of the Mashery^® Admin Dashboard.

3. Perform a manual sync of the Services and Developers in the "Cloud Sync" page of the Mashery^® Local Cluster Manager, as described in step 7 earlier in this manual.

4. Construct a test API call for the API you wish to test.

5. Execute the API call against the instance. Unless you have set up a domain name for the instance, your API call will need to be made against the IP address of the instance directly. You can find the IP address as described in step 12 earlier in this manual.

Should you use a hostname or IP in your test call? When a service is setup in the dashboard, the hostnames (IP addresses as well could be used) that will consume the service are defined. When a call is made to the proxy, the hostname used for the call must match one of the hostnames setup in the dashboard for the service, otherwise the call will fail. If you make a call directly to one of the instances using its IP address and that IP address was not configured in the service definition, then the proxy returns a 596 error.

If you receive the expected response from the API, then your instance is working properly.

(51)

Testing the New Instance

Tracking the database restore and replication status

Mashery Local slave node registration process provides a status endpoint that helps to track the asynchronous steps of database restore and replication status. However, these steps are processed in the background, so there is no active feedback on completion or failure of processes.

Note: The status endpoint (registration_status.py) is an experimental API and is subject to change in later implementations.

There is no need to Enable API Access on the node for this endpoint to function. See Configuring OAuth 2.0 API Access.

To obtain the database restore and replication status, type the URL of the endpoint in your browser.

Example:

https://<Mashery_Local_Slave_IP>:5480/service/mashery/cgi/replica tion_status.py

The endpoint returns the following JSON:

{

"replication_status":

{

"restore": {

"error": false, "errors": "",

"log": "1. transfer backup from master\nMon Aug 22 18:38:04 UTC 2016\n\n2. unzip backup\nMon Aug 22 18:38:41 UTC 2016\n\n3.

stop slave\nSlave stopped\nMon Aug 22 18:38:41 UTC 2016\n\n4. restore from backup\nMon Aug 22 20:36:18 UTC 2016\n\n5. start slave\nSlave started\nMon Aug 22 20:36:18 UTC 2016\n\n6. done\nMon Aug 22 20:36:18 UTC 2016\n\n", "complete": true

}, "replication": {

"last_error": "",

"seconds_behind_master": "250832\n", "slave_io_running": "Yes\n",

"slave_sql_running": "Yes\n"

} },

"error": null }

TIBCO Mashery

TIBCO Mashery

Local 3.1.1

Installation and Configuration Guide

August 2016

www.mashery.com

Copyright Notice

© 2016 TIBCO Mashery™ All rights reserved.

Mashery® software is provided under a written agreement and may be used or reproduced only in accordance with the terms of that agreement. It is against the law to reproduce Mashery®

software on tape, disk, or any other medium for any purpose other than the licensee’s expressly authorized use.

Trademarks

TIBCO and TIBCO Mashery are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

575 Market Street, 15th Floor San Francisco, CA 94105

Part Number: IO-Docs-cfg-04-2012

Contents

Chapter 1 About this Guide ... 5

Chapter 2 Prerequisites and Installation Overview ... 7

Chapter 3 Installing and Configuring Mashery

Local ... 10

Chapter 4 Advanced Configuration and Maintenance ... 26

Chapter 5 Using the Adapter SDK ... 36

Chapter 6 Testing the New Instance ... 50

Chapter 7 Troubleshooting Guide ... 53

Chapter 1

About this Guide

Introduction

Assumptions

Chapter Overview

Conventions

Chapter 2

Prerequisites and Installation Overview

Deployment Topology

Hardware and Software Requirements

Overview of Installation and Configuration Process

Chapter 3

Installing and Configuring Mashery ® Local

Deploying the Mashery

Local OVF Template

Configuring the Mashery

Local Cluster

Configuring a Mashery

Local Master

Configuring Slave(s) to the Master

Configuring the Load Balancer

Configuring the Instance

Chapter 4

Advanced Configuration and Maintenance

Configuring Quota Notifications

Configuring LDAP

Configuring OAuth 2.0 API Access

Making OAuth 2.0 Calls

Sample Call

Understanding the OAuth 2.0 API

Configuring JMX Reporting Access

Installing Updates

Updating Repository Settings

Chapter 5

Using the Adapter SDK

Adapter SDK Package

Mashery

Domain SDK

Mashery

Infrastructure SDK

SDK Domain Model

Extended Attributes

Pre and Post Processor Extension Points

Listener Pattern

Event types and Event

Event Listener API

Implementing and Registering Processors

Downloading the SDK

Implementing the Event Listener

Implementing lifecycle callback handling

Adding Libraries to Classpath

Deploying Processors to Runtime

Packaging the Custom Processor

Uploading the Custom Processor

Enabling Debugging

Caching Content

Chapter 6

Installing and Configuring Mashery ^® Local