TIBCO Cloud Mashery API Developer Blog

We are pleased to announce the general availability of Call Inspector – a tool that will allow you to debug API calls as they flow through Mashery Traffic Manager. With this tool, you are able to respond faster to problems reported by your API users by being able to narrow down issues with their API calls. Additionally with the tool you can gain insight into historical transactions for auditability.  

The feature allows you to turn on call capture (or verbose logging) for a specified duration with all-inclusive criteria or by filtered criteria e.g. specific APIs and end-points, specific status codes etc. Verbose logging is produced for calls that meet the call capture criteria.

The call viewer tool allows you to drill down into each call that has a verbose log available in the system . You can review details such as the call request as it hits Mashery, as its processed by Mashery before being submitted to API back-end system, response as its delivered by back-end system and response as its processed by Mashery. This level of visibility also allows you to drill down and narrow down the problem area and address questions such as whether the issue is due to processors applied for that API end-point or not. Call viewer tool also provides ways to filter out calls for viewing by criteria such as API Key or Package Key so you can zoom in on specific problem calls quicker.

Call Inspector has a number of access control and management features as well.  It's an optional and controlled feature that some users with APIs that have security and privacy oriented requirements may not want to utilize or restrict which endpoints are enabled.  You can control which employees may turn on the feature and for which specific data flows.  You may control which employees may view the log content.  The system also automatically generates notifications to email groups that wish to be informed when the tool is used.  Finally, any service that is marked as requiring high security rules will never be logged by the system period. 

The feature is available for use by all Mashery customers up to a certain consumption level depending on the Mashery plan you are subscribed to. For details on enabling this feature for your area, please contact Mashery Support or your Mashery Customer Program Success Manager

Mashery is pleased to announce the availability of a new feature that enables customers to add more security around the content that is published through the Mashery Portal.  The new Secure Search Results feature, automatically turned on for all customers, takes advantage of the role permissions already setup in a customer's portal and uses those permissions to determine if a portal end-user will actually see that item when they are searching for content.  The ability to secure search results, i.e. hiding items completely from view even if those items contain words or phrases matched by the search engine, makes it easier to publish sensitive information that is critical for only select audiences.  For example, you might be creating a new API and want specific developer partners to engage in the documentation review process for this API but you do not want anyone else to catch wind of this.  By setting role permissions on this set of documentation, you can be assured of the fact that no one else, other than those roles that you want to see this content, will be able to get to this information, whether by browsing or searching.

Below is an example of this in action. The first picture shows a piece of content that is appropriate for all types of people coming to my portal.  As such, when they search for something, that content item can in fact be displayed in the search results.

The below picture shows a piece of content that is appropriate only for a specific audience: people who belong to my Large Partners, e.g. maybe those that are paying me a bunch of money to be in my partner program.  As such, when they search for something, that content item can in fact be displayed in the search results, but only when the end-user searching for that content has the right role, i.e. Large Partners.

With Tuesday night's release, we have added a useful little feature to Mashery's OAuth API - a new method to update access tokens. Comes in handy if you have the need to update the access token attributes such as scope, user context, time to expire. Details on this new method and how to use it available here

Also recently we added another feature to the OAuth accelerator that provides an option to allow Mashery to generate multiple access tokens for the same user context. This is an option you can leverage if you have  requirements that need an app end-user wanting to run the app on multiple devices.

We listened to your feedback and are excited to let you know about a new feature addition – wild-card parameters are now allowed in end-point definitions! This will allow you to simplify your setup a great deal and yet not lose the level of visibility you require into method-level API usage.

The feature is easier explained with a specific example. Let’s say you had to setup patient related information as an end-point in the system, but the end-point needs to accept a variable patient ID value in the request path. You can simply use a meaningful parameter to denote patient ID in the request path such as {patientID}. You could also use the same correspondingly in the end-point path as shown below:

Also if you need fine-grained reporting and analytics on the usage pattern by the {patientID} wild-card parameter, you can configure appropriately in your methods configuration as shown below:

For the above example, if a request came in as say api.acmehealth.com/v1/patients/945673, it will be matched to this end-point in the system. The request will be routed to backendservice.acmehealth.com/internal/patients/945673/data. In addition in your method level reports, because of your methods configuration in API settings, you can see usage for v1 patients 945673

In essence with this feature, you no longer have to setup either multiple end-point paths for different patient IDs in the above example or take a coarse-grained approach to setting up end-points such as v1/patients/. The former was cumbersome and sometimes near impossible if you had multiple combination of such IDs in your request path. The latter will not necessarily allow you to get the right type of fine-grained reporting on your API usage. Wild-card parameters in end-point paths allow you the right type of flexibility with your end-point setup

Mashery is pleased to announce the availability of a new feature that enables our customers to apply role-based access control rules on the APIs published through the Mashery platform.  Whether ensuring that only internal developers see the I/O Docs for internal APIs or special partners registering for APIs that only they should get access to, Access Control on APIs can be used to ensure that users with specific roles can get access to only those APIs, whether services or package plans, that you want them to get access to.  This feature allows a customer to expand its use of the portal as a documentation, learning and self-service key provisioning application, securely pushing out APIs that would have normally been hidden behind firewalls or administrative processes.

For each API in the system, whether a service or a package plan, customers can now associate roles and permissions, effecting the portal experience such that the associated I/O Doc, if defined, is either shown or hidden and the API itself is either shown or hidden in the application registration form, i.e. the page where developers get new keys.

Let's walk through an example.

An API provider currently exposes a Retail API through their Mashery-powered portal.  Any developer can come, register, see the I/O Docs and get keys for that API.  The provider now wants to allow its internal developers to also have the same sort of experience - seeing I/O Docs and getting keys - for an internal only API.  In this case, the company has an HR related API that they want to expose through Mashery but in a controlled way.

Before Pictures of an Internal Developer

An internal developer has logged into the portal and clicked on the I/O Docs page. At this point, they only see the one that is visible to all developers, regardless of role.

The same internal developer has logged into the portal and clicked to get a new key. At this point, they only see the API that is visible to all developers, regardless of role.

Administration Change

The administrator has gone in and enabled the internal API as being visible to users with the Internal Developer role, both on the I/O Docs page, i.e. "read" permission, and the application registration page, i.e. the "register_keys" permission.

After Pictures of an Internal Developer

The internal developer has logged into the portal and clicked on the I/O Docs page. At this point, they now see the I/O/ Docs for two APIs, the one that is visible to all developers, regardless of role, and the one targeted to Internal Developers only.

The internal developer has logged into the portal and clicked to get a new key. At this point, they now see two APIs, the one that is visible to all developers, regardless of role, and the one targeted to Internal Developers only.

NOTE: The ability to set access control rules, per the above, is available in your Mashery administration dashboard. If you want your developer portal to enforce those rules, please contact support@mashery.com and we will enable that for you. Once enabled, there will be default permissions set in order to not disrupt the current portal behaviors experienced by your developers, i.e. we can turn this feature on for you and there is no immediate impact to the portal experience. You can change those default permissions as you see fit.

We recently added a couple new feature improvements to our OAuth accelerator that will add that extra layer of security to your OAuth implementation

• All applications that use an API that have OAuth 2.0 enabled will have a field available now to pre-register the redirect URI. While configuring the OAuth accelerator for your API (under API settings), you now have an option to mandate that only calls validated against this pre-registered redirect URI are allowed to access your API.  OAuth API methods createAccessToken and createAuthorizationCode now include these supporting validations as well. For detailed documentation on the OAuth API refer to the documentation section

• You now have an option to configure TTL for refresh tokens as well. By default this is not enabled.

The Mashery API has included support for interacting with the Developer Class object for some time, but the documentation was incomplete.  A full edit was completed and is now available in the documentation section.

The Mashery-supported, integrated I/O Docs capability now supports POST requests that have POST body data, as well as passing in data via the headers and parameters.  With I/O Docs, customers can present interactive documentation that makes it easier and faster to learn about their APIs.  With this most recent update, customers, who have POST methods that need to support data being passed in via the request message body, can use I/O Docs to document these particular parts of their API.

I/O Docs is configured via the Mashery administration console, in the I/O Docs section of Portal Settings.  If you need help setting up I/O Docs, please contact support@mashery.com.

Example Configuration

{
   "name":"acme daily deal api definition",
   "version":"1.0",
   "title":"Acme Daily Deal API",
   "description":"This Daily Deal API is used to find the most current daily deals.",
   "protocol":"rest",
   "basePath":"http://api.acmeapparelstore.com/",
   "auth":{
      "key":{
         "param":"apikey"
      }
   },
   "resources":{
           "Review Daily Deal":{
               "path":"deal",
               "httpMethod":"POST",
               "description":"Submit a review on the the most current Daily Deal.",
               "parameters":{
                      "review": {
                        "required": "true",
                        "default": "",
                        "type": "textarea",
                        "description": "This is an HTTP POST method and supports sending data across in the post body.",
                        "location": "body"
                      }
               }
            }
         }
      }
   }
}

Example result in I/O Docs Application

As you work with external developer partners or internal employees, sometimes those people using your APIs leave their jobs, their projects or otherwise no longer have the need to have their Mashery developer account associated with the applications, and associated API keys, that they originally created and worked to build.  In these situations, where you might want to transfer control and management of these "orphaned" or "abanonded" applications, Mashery now supports changing the owner, or related developer/user, for applications and their corresponding API keys.  It is a simple process by which the authorized administrator can edit the application with the Mashery administration console and pick the new developer/user; an example screenshot is shown below.  Once the switch has been made, the old owner of the application, e.g. that person who just transferred departments and as such is no longer available to work on the application, can no longer see that application, its API keys and associated reporting data from within the My Account area in your Mashery-powered Developer Portal.  This function is also available in the Mashery V2 API through the application.update and key.update methods.