Boomi Cloud API Management Developer Blog

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.

Today's developer portals often leverage a well-known web feature: discussion forums.  Useful for self-service support, knowledge sharing and general discussion, forums are a great way to connect developers with your API program and to each other.  These collaboration areas are one of the ways to forumalate a two-way discussion between you and your community.  Not only can you talk to your developers but they get to express themselves, whether asking questions about API usage or collaborating with others on problems or ideas.  And when they do participate, developers want the ability to do so beyond what simple text input areas on a form provide.  Whether to emphasize a point, link to other developer portal or external resources or help others through code examples, developers want more and better ways to communicate and collaborate.  In discussion forums, one way to do this is to enable developers to add HTML-style formatting, hrefs for links to other resources and, when providing code examples, see code highlighted in a similar way to how they would in their favorite IDE.

To address these needs, Mashery announces the arrival of a long awaited enhancement: markup in Forums!  Utilizing a well-known, dev-friendly syntax called Markdown, this feature gives the developer the ways to achieve their formatting and functional needs when posting to Mashery-powered discussion forums.   The following is the list of features in this release: 

1. Ability to use Markdown for formatting of posts and comments.
2. Ability to drop in sample code and have it highlighted, using language-specific convention and styles.
3. Ability to have links generated automatically, simply by typing in the URL, e.g. http://www.mashery.com , rather than the full Markdown syntax.
4. Faster performance due to enhanced caching and architecture.
5. Pagination of posts and comments, i.e. if a conversation includes a large number of comments, those will be paginated, making it easier to navigate.
6. Last but not least: Preview!  As people create their posts or comments, they can always see what it will look like when saved; especially important when using complex Markdown syntax or just starting out.  

A couple of demonstration screenshots can be seen below.  

 We hope that you'll find these enhancements useful.  Do not hestitate to provide feedback or contribute other ideas on how Mashery can make discussion forums even better!

Screenshot #1

Screenshot #2