TIBCO Cloud Mashery API Developer Blog

We launched another improvement with the types of information you may inject into headers this week: Mashery Message ID.  The Mashery Message ID is a globally unique ID (GUID) that we generate for every API call that is processed by our network.  This GUID is a possible mechanism for you to create a golden thread between your partners, Mashery, and your own systems where all parties have a single ID they might use to debug issues.  By all parties having a single ID with which to track an API event, all are able to quickly find the specific log entries or debug output necessary to troubleshoot problems.   

You may toggle this feature on by navigating to the API Settings->Endpoints->Properties page.  There you will find two new options: "Include X-Mashery-Message-ID in Request" and "Include X-Mashery-Message-ID in Response".  This allows you to control whether the GUID is included in the headers of the request sent to your API hosts and/or the response sent to your partners.  By including both, you have the potential to put in place new support capabilities and tools for your teams and have the golden thread.

We hope you find this useful.

We launched a nice small feature today that allows you to configure Mashery to inject the ID of the API being consumed into the call headers that are passed to your API hosts.   This ID is primarily used by the Mashery API.  You use it to direct the Mashery API to perform operations on your configuration data that resides in Mashery.  You might, for example, read in this ID and use it as an input parameter in an inline API call you make to Mashery to lookup an application name or an attribute of the partner's registration information.  

You may toggle this feature on by navigating to the API Settings->Endpoints->Properties page.  There you will find the option for "Pass X-Mashery-Service-Key Header in Request" with a yes/no option.  When set to 'Yes', inbound calls to your API will receive a new header of X-Mashery-Service-Key with the API ID for it's value.  

Spam, spam, spam.  One cannot escape it, even in the API world.  With the growth in popularity and usage of APIs has come an increase in the amount of spam generated in developer portals.  Whether adding nonsensical spam to forum posts or advertising in the form of blog and documentation comments, spammers have begun to litter the developer portals of successful API programs.  Now Mashery customers have a way to control the garbage created.

I'm happy to announce the availability of a feature that enables our customers to moderate user-generated content (forum posts/comments, blog and documentation comments) for spam.  You can use this feature by going to the Portal Settings->Content section of the Mashery Dashboard and selecting "Moderate Spam" for each content type for which you want spam managed.  When "Moderate Spam" is selected, each piece of user-generated content, e.g. a forum post or comment, will be routed through a spam detection algorithm and if the piece of content contains what could be spam, it will be placed in a moderated state and held for review by portal administrators.  Other content that passes the spam filter will automatically appear on the site.

Screenshot #1: Selecting "Moderate Spam" in the Dashboard

Every day, Mashery customers use performance data from the Mashery Dashboard's Reports section to manage their API programs.  From developer activity and method usage to conversion rates and geographic query distribution, Mashery customers get the information they need—in tables, charts, and downloadable spreadsheets—to make business and operational decisions. 

It's not surprising, then, that lately we've been hearing from more and more customers who want to integrate this valuable information with their own data warehouses and analytics tools.  So I'm happy to announce that Mashery is introducing an API for grabbing API reporting and analytics data. 

The new Mashery Reporting API exposes all the information used to build the Mashery Dashboard's charts, tables and spreadsheets.  It's a RESTful API that returns either JSON or CSV formats.  Check out the documentation at http://support.mashery.com/docs/read/mashery_api/20_reporting or, even better, try it out (after signing in with any Mashery V2 API key) using I/O Docs at http://support.mashery.com/io-docs.

Screenshot #1: Reporting API within I/O Docs

Screenshot #2: Example IPad application built using the Mashery Reporting API

Hot from the desk of "should have had this awhile ago", we added a small feature last night to pass through the inbound host header to your API hosts.  Previously, if you wanted this value, you could only toggle on a feature to pass it through a custom Mashery header of x-Mashery-Host.  While that feature remains in place, we also added the ability to simply pass it through as the basic http host header you'll receive.  

You can toggle either of these features on the API Settings->Endpoints->Properties page.  There you will find options for both.  Set either or both on, and the inbound host header is passed into the header attribute you have requested.  

Many APIs today support multiple protocols and Mashery helps you manage that complexity.  Many REST APIs support multiple response formats, with XML and JSON being the most popular.  We released a small feature improvement that improves our handing of this type of multi response format API.  

We've added the ability to more easily configure your service to use http accept headers to control response formats.  While we had already supported a number of methods to request specific response formats, our Error Set selection logic previously required a custom adapter to respond to accept header directives.  We now support configuration via simple UI.

For example, in the call below, the application wishes to receive a JSON formatted response from the Acme API.

curl -v -H 'Accept: application/json' 'http://api.acme.com/v1/getList?api_key=fakekey' 

Your Mashery service needs to be configured to recognize the accept header of 'application/json' to have Mashery error responses (e.g. 403 Acount Inactive) return in JSON format.  To use this feature improvement, configure the Error Set Selection logic to respond to accept header directives like this:

1. Create your error sets as usual in the "Errors" tab of the API Settings configuration screens
2. On the endpoint you wish to configure for accept header based response formats, navigate to the "Endpoints->Properties" tab
3. In the Errors Configuration area, select "Accept Header" from the "Call Requested Selection Logic" drop down.
   
   
   
   
4. Configure the accept header values you wish to support in the "Call Requested Selection Location" text field.  The field accepts content types in name/value pairs separated by commas.  The format is 'contenttype=error set name'. 
   • Example: application/xml=xml, application/json=json
   • In this example, 'xml' and 'json' should be the names of the error sets you've created that respond with XML or JSON formats.

Now, when your partners request XML or JSON in their accept headers, the Mashery service will respond with appropriately formatted responses, all through simple configuration.

In Tuesday night's release, we added a small feature improvement to the algorithms we support for detecting the method name on API calls.  For SOAP APIs, the new "SOAPAction" capability is available in the "API Method Name Source" drop down on the Endpoint Properties tab within API Settings.  When set, the SOAPAction http header variable value will be used as the method name for the reporting and method limiting capabilities.

Mashery I/O Docs is an interactive API exploration and testing tool that runs on your Developer Portal. It enables your developer partners to perform API calls directly within the documentation using their own API keys with described form-based parameter inputs fields and easy-to-read color-coded and formatted payload outputs.

A couple months ago, Mashery launched a limited release of I/O Docs on several developer portals. I/O Docs is based on a culmination of reviewing data usage patterns and feedback collected across hundreds of developers who have been getting started and building applications using the product. We demonstrated early-stage versions at developer outreach events and hackathons for several months before the official product release.

We are happy to announce that I/O Docs can now be enabled and configured within the Administration Dashboard. The current release version supports RESTful APIs with either XML or JSON output and most API key authentication schemes. Our product and engineering teams are continuing to iterate and improve I/O Docs to include support for additional protocols and auth schemes.

For some forward-thinking APIs looking to embrace the interactive API docs trend we see companies such as Google, YQL, Klout, and Posterous. I/O Docs may serve as a full-on replacement for traditional long-form documentation. However, it can also serve as a useful testing tool and debugger to regular long-form style documentation, especially in cases where APIs have more advanced authentication and request methods. For full documentation on enablement and configuration, please contact your client solutions manager.

Mashery clients tells us they get tremendous value from the reporting and analytics data surfaced through the Mashery Dashboard. From detecting trend changes in API traffic to evaluating the value of developer apps, clients can leverage the metrics and underlying data to optimize their API programs.  

However, as their APIs become more successful and visible, API managers also find that colleagues from around their organizations are clamoring for this data. Demand is coming from marketing folks tweaking messaging, business analysts evaluating API investments, and executives trying to understand how the API powers the business. 

To satisfy this appetite for API-related reporting without sacrificing security, Mashery has released a new user role: Reports User.

People with the Reports User role can access reporting data, and only the reporting data, from within the Mashery Dashboard. When they log into the Mashery Dashboard, their view will be similar to the one below, with access only to the Reports tab.  Unless they have other roles, Reports Users cannot make changes to API settings, developer accounts, or portal content.