TIBCO Mashery® Self-learning Exercise

Table of Contents

• Introduction
• Basic topics
• Step 1: Managing your first API
• Step 2: Providing access through a package and a plan
• Step 3: Sharing your API with developers
• Step 4: Creating API documentation
• Step 5: Test your API

Please refer to the TIBCO Cloud Mashery® QuickStart Guide to sign-up for a TIBCO Cloud? and connect to Mashery.

Introduction

What are the main steps you need to follow to get your first API published?

1. Create an API definition. This details how Mashery will handle the request traffic (routing).
2. Create a Package and Plan. This defines the available access rights and the service level (e.g. rate limits).
3. Create your API documentation.

All these items are covered in the basic topics section and in 5 steps it will guide you through creating, sharing, accessing and testing your API.

The examples used for the API will use a publicly available RESTful sample provided by TIBCO at https://integration.cloud.tibcoapps.com. This example is developed and deployed on TIBCO Cloud Integration platform (Visit http://cloud.tibco.com/ for more information).

Basic topics

Step 1: Managing your first API

Let's get started!

Connect to the Mashery Control Centre. This will open the ?Get Started? Welcome page that lists a number of common tasks. The general configuration of an API is as follows:

1. First, you have an API Definition that represents the API that you would like to expose. An API can be coarsely or more granularly configured, but the general need is to define the specific details around how the Mashery Traffic Manager will process the call (Authentication, Routing, Error handling, etc.).
2. Second, within the API Definition, there are Endpoint Definitions for the API, defining where and how you want to route traffic.
3. Third, within the Endpoint Definition, you can optionally define Method Definitions for the Endpoint, providing detail on how the Mashery Traffic Manager can understand the different methods around your API, giving you the ability to create further granularity in rate limiting, authorization, API traffic reporting, response validations, and response filters.

We'll start with configuring an API Definition with Endpoint Definitions. (Method Definitions will be configured in the following section). Let's start by creating the sample API.

HINT - As you navigate through the pages you will see question mark (?) icons next to the fields. Clicking on the icon will bring up help information about each of the fields.

1. Click on API Definitions on the Get Started page. You should be on the Get Started page after logging into the Dashboard (also called Control Center).

    

   

    

   New APIs can also be created by navigating to Design > APIs.

    

   If you haven't created an API in your area yet, you'll see a "Create your first API Definition" button. 

    

   

    

   If you already created an API in your area, you can hit the () button to create a new API. 

2. Enter a name for your API: Acme API
3. Description: We can leave it empty for now
4. API Version: 1.0
5. Organization: Leave as the default  (You can use the drop-down list to select one of the other pre-define Organizations if you wish).
6. Click the Create button on the top right.
7. After hitting Create, you will now enter the API Definition page for Acme API. This is where we will see the Endpoint Definitions for the API once they have been created. 

    

   

8. On the left-hand side, you can see all the different options available, which include:
   1. API Definition & Endpoint List ? The list of all the endpoint definitions created for the API. (Your current view)
   2. API Definition Settings ? Overall API definition settings, including the name, description, and version we just set
   3. Security Settings ? Whether we want to enable OAuth for this API
   4. Error Sets ? Custom error messages we want to create for this API
   5. Access Control ? To which groups we want to allow access to view this API
   6. Performance Acceleration ? How we want to set-up caching for this API
9. Click on the Create your first Resource Endpoint button.

    

   

    

   If you're coming back through this guide and already created an endpoint, you can click on the () button to create another endpoint.

    

   Now we need to fill some of the fields:

   1. Name for your Endpoint: Default
   2. Customize your Public Endpoint Address:

       

      The first textbox will be prefilled to your trial area. For example:

       

              evalXXXX.api.mashery.com

       

      In the second textbox enter: acme/v1

       

      

       

      For the first textbox, this value will typically be set to a domain name that would match your domain such as api.your-company-name.com or service.your-company-name.com. For the purposes of this quick start, we will use the domain name provided by Mashery.

       

      For the second textbox, the Path used on the Public Endpoint Address identifies this specific endpoint configuration for this specific service/API, with an assumed wildcard at the end of the path. The path prefix used must be unique across your Mashery instance.

   3. Next, we need to set the target Endpoint address:

       

      Set the Protocol to  HTTPS

       

      First textbox: integration.cloud.tibcoapps.com

       

      Second textbox: u4gmknzehvjvneeh54tpksna5fvtvmdx/ (include the trailing /)

       

      Third textbox: (leave blank)

       

      

       

      For values in the first textbox, you will need to request your hostnames to be white-listed on Mashery. Please contact us via http://support.mashery.com/ for enabling specific domains to be white-listed.

       

      The second textbox provides the ability for a URL rewrite from the configured Public Endpoint Address.

       

      Given the scenario thus far, the URL of http://evalXXXX.mashery.com/acme/v1/product will map to https://integration.cloud.tibcoapps.com/u4gmknzehvjvneeh54tpksna5fvtvmdx....

   4. Click Create at the top right of the screen
10. Click on Access Control in the left-hand menu.

     

    By default, no one can see this API as you update your definition. You can create custom roles to enable specific developers to see this API. For this quick start, we will assume that we allow Everyone to see the API.

    1. Click on Everyone on the Unselected Roles column, which will add it to the Current Roles

        

       

    2. Click Save on the top right
11. Now will need to change one element of the default Mashery behavior.

     

    By default, Mashery will pass all query parameters it receives onto the backend application, including the API key. Some backend applications don?t handle unexpected parameters well, maybe by giving an invalid response or a message saying it received too many arguments.

     

    Mashery provides fine control over what is sent to the backend application, so we have an option to exclude the passing of the API key.

    1. Click on API Definition & Endpoint List on the left-hand menu.
    2.  You will see in the list the Default resource endpoint definition that you created in Step 8. Click on Default and you will be taken to the Endpoint definition.
    3. On the left-hand menu select More Settings
    4. Set the Remove API Key and Signature from Endpoint Call to Enabled

        

       

    5. Click Save at the top right of the screen

Step 2: Providing access through a package and a plan

We've created our first API, but no one has access to the API as of yet. You can try calling your API at this point, but you will receive an error. If you tried an HTTP GET to http://evalXXXX.api.mashery.com/acme/v1/product, you would see a 403 Forbidden error with "Developer Inactive".

In order to get access, we must first create a Package and Plan that will encapsulate which APIs a developer can sign up for, how keys are generated, what rate limits will be set, and more. The Package will define what API?s are available to the developer. The Plan will define the access they have to the APIs. For example the number of calls per second. Let's now define the Package and add the API to it.

1. Navigate to the New API Package definer.
   1. Option 1:
      1. ??Click on TIBCO Mashery home logo on the top left.
      2. Click on the Create a new Package button.
   2. Option
      1. Navigate from the menu bar to Design > Packages.
2. Name: Acme Package

    

   

3. Click the Create button on the top right.
4. You will now be at the API Package & Plan List screen, which looks similar to the API definition page from the previous section.

    

   We also see additional options available for the package on the left column, which include:

   1. API Package & Plan List ? The current screen we're on
   2. API Package Settings ? The name and description of the Package
   3. Key Properties ? Key length and if we require shared secrets
   4. Notification Settings ? Whether and when to send notifications when nearing quota limit or over quota/throttle limit, both for developers and administrators

       

      

5. Click on the Create your first API Plan button.

    

   Name: Starter Plan

    

   Description: We can leave it empty for now

    

   

    

    

6. Click Create on the top right.
7. You should now see the created plan as is shown in the image below

    

   

    

    

8. We will now add details around the Plans. Click on the name of the plan (Starter Plan) or the edit icon (looks like a pencil on a notepad).

    

   

    

   You should now see the left-hand menu change with additional options:

   1. ????Plan Contents ? Where we can set method level rate limits and response filters (more on this later).
   2. Plan Designer ? Which APIs are allowed in this plan
   3. Plan Settings ? The name, status, and description of the plan.
   4. Key Properties ? How keys are requested (self-service, moderated)
   5. Rate Limits ? Throttle and Quota limits
   6. Access Control ? Who has visibility to this plan
   7. Notification Settings ? Where you can assign a specific notification template
9. Click on Plan Designer in the left-hand menu.
   1. Click on the checkbox next to the API Definition Acme API Ver:1.0, which will turn it green.

       

      You can navigate to the next level by clicking anywhere in each box except on the checkbox.

       

      You should notice the Default endpoint is automatically selected.

       

      

       

       

       

      Right now, we won't have any methods available, as we haven't defined them.

       

      So far what we have defined will allow any API call that matches http://evalXXXX.api.mashery.com/acme/v1/* to be allowed through with this plan. We can potentially allow for access to all APIs, limit to specific endpoints or even any unidentified method.

   2. Click Save on the top right
10. Click on Key Properties in the left-hand menu.
    1. Set the following values

        

       Self-service Key Provisioning: Enabled (default value)

        

       If we were to select Disabled, we would distinctly only allow an administrator to provide access on behalf of a developer, versus allowing a developer to get a key through self-service provisioning.

        

       Make sure to set Maximum Allowable Keys to 4 (should be the default)

        

       Make sure to set Number of Keys allowed until Moderation to 1

        

       Setting this to 0 means that administrative approval is required before access is granted for an application Key. Setting this to 1 or more, means keys are provided through self-service.

        

       

        

        

    2. Click Save on the top right
11. Click on Rate Limits in the left-hand menu.
    1. Here we want to set the Plan limits as follows:

        

       Throttle 1 (calls per second)

        

       Quota of 2500 and Quota Period of Day (calls per day)

        

       

        

        

    2. Click Save on the top right
12. Click on Access Control in the left-hand menu.
13. Click on Everyone on the Unselected Roles column to add to the Current Roles

     

    By default, no one can see the Packages and Plans that are defined. Custom roles can be created to only enable specific developers to see if specific plans are available. For this quick start, we will assume that we allow Everyone to see the plans we've created.

     

    

14. Click Save on the top right

Step 3: Sharing your API with developers

Now that we have an API, a package, and a plan, we can register as a developer and sign up for access to the APIs. For now, you can simply use your existing administrator account to register for Keys.

1. Navigate to the Portal at http://evalXXXX.mashery.com. You can go directly to the URL from a new browser window or from the Control Centre, select the Down Arrow on the top right-hand side of the age and select Developer Portal.

1. Sign In, if you have not done so already
2. Click on My Account on the top
3. Under My API Keys, click on Applications
4. Click on Create a New Application
   1. Name of your application: Starter App
   2. Web Site:  Enter a valid URL  (The url entered needs to be in a valid format, so it doesn't matter if the website isn't accessible yet).
   3. For now, you can ignore the rest of the fields up to Register Callback
   4. Scroll down to ?Select which Web APIs this application will use?. Issue a new key for Acme Package and Starter Plan should already be selected by default.

       

      

       

      If you've created multiple packages and/or plans, you may see other packages that are checked off by default. Make sure to uncheck all other packages other than the one we have just created. If you leave each one checked, your application would get a different API Key per package.

   5. Check the "I agree to the terms of service"
   6. Click Register Application
   7. We now have access to the Acme APIs using the new API key that we've registered. You should have also received an email on the status of your registration. Given that we have not required approval for the first key request, your key should automatically be active. If we require moderation, we would see the status of waiting.

       

      

Step 4: Creating API documentation

At this point, we can potentially test our APIs using your favorite client app. (For example, enter http://evalXXXX.api.mashery.com/acme/v1?api_key=25puf2ft6d9y6zrud3cc49zj... a browser). However, we're going to first create an interactive documentation page.

Let us be clear about what the following steps do.  Setting up IO Docs doesn?t affect which resources are available via Mashery. At present we have defined it so that all services exposed via https://integration.cloud.tibcoapps.com are available via http://evalXXXX.api.mashery.com/acme/v1.  Now what we are configuring, is how a portal user can interact with the services via the IO Docs page on the portal. Go back to the Control Center Admin session.

1. Navigate to Design > I/O Docs on the top menu.
2. You can click on the IO Docs Settings button on the top right to modify the general settings for the IO Docs Page Title and Description. We will not make any changes to these options in this quick start.
3. Here we can see a list of all the APIs defined.

1. Click on Acme API. Here we see a default IO Docs template that has been created based on the API and Endpoint definitions we've created in the earlier sections.

    

   On the top right, we have an Import that allows us to import an existing IO Docs JSON file or WSDL (for Web Services proxied through Mashery).

We will need to make a number of updates to appropriately point I/O Docs to the appropriate API endpoint and paths for each method. Make the following edits in the I/O Docs JSON:

• "basePath": "http://evalXXXX.api.mashery.com/acme/v1"

Under  "exampleMethod".

• "description": "Get all products"
• "path": "/product"

Under the "parameters", there is a sample "exampleParameter" created, change "required" to false.

 (Optional) You can also change the names of the methods (e.g. instead of exampleMethod you can use GetAllProducts), which will be the display name used on the I/O Docs page.  Your completed I/O Docs definition should look like the example below.  {   "name":"Acme API",   "title":"Acme API",   "description":"",   "version":"10",   "protocol":"rest",   "basePath":"http://evalXXXX.api.mashery.com/acme/v1",   "auth":{     "key":{       "param":"api_key",       "location":"query"     }   },   "resources":{     "Default":{       "methods":{         "GetAllProducts":{           "description":"Get all products",           "httpMethod":"GET",           "path":"/product",           "parameters":{             "exampleParameter":{               "description":"",               "default":"",               "required":false,               "location":"query"             }           }         }       }     }   } }

1. Click Create to save the changes.

Step 5: Test your API

1. Navigate to the Developer Portal and go to API Console. You can also go directly to http://evalXXXX.mashery.com/io-docs.
2. Acme API will automatically be selected in the dropdown menu. If you have more than one API definition, you will have to select your API from the list.
3. If you have followed the instructions through this document, you should have your API Key listed in the App/Key drop-down. For unregistered users or users without a key, they will just see a text box, which is what you would see if you click the Manually provide key information link.

1. With Starter App key selected, under the Default heading, open up the GET exampleMethod (it may be a different name if you optionally change it).

    

    

    

   Click the Try It! button to test the API.

    

   You should see the successful sample request and response.

1. You can see the sample request URI with http://evalXXXX.api.mashery.com/acme/v1/product?api_key=your-api-key. You could directly try this using your favorite client (e.g. cURL, Postman, REST Client, SoapUI, etc) or even add it to your browser.

    

   You can also change the URL by replacing the product with the order, as this is another method available on this API

Congratulations you've now completed the basic quick start! We suggest that you review the steps you have done to make sure you have understood all of the processes.

Then you can continue with the additional more advanced topics in this article.

? Back to the Mashery Wiki