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.

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.

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.  

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

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

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.  

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.

With the growth of APIs as a true source of business transformation, Mashery continues to be witness to a growing number of customers leveraging the power and simplicity of Mashery’s truly multi-tenant API management platform. In addition, a steadily increasing number of our customers are benefiting from the flexibility of Mashery Local – the on-premise version of Mashery’s Traffic Manager that can be deployed in their own data-center

We at Mashery, are dedicated to continuously improving Mashery Local based on your feedback and are pleased to announce the availability of Mashery Local version 1.3. Some useful additions to this release:

• JMX Service Monitoring: You can now monitor your Mashery Local instances using a JMX based service. A Mashery Local administrator can enable the JMX based service and you can monitor securely (after importing the necessary SSL certificate) using your favorite JMX compliant monitoring tool.
• OAuth Accelerator: Our OAuth Accelerator now includes an API within Mashery Local so you no longer need to call out to our Cloud API.
• LDAP Enhancements: While we have had support for LDAP based authentication in our previous Mashery Local releases, this release allows for user-objects and PAM filter based rules for your LDAP authentication
• Upgrade Ease: This release provides more flexibility in upgrading additional components of the solution via the Cluster Manager UI, greatly reducing the need of requiring a new virtual instance deployment in the future.

For customers with a Mashery Local license, please contact us at support@mashery.com to obtain the image and release notes.

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.

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

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.

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.

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 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

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.

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.

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

With the release last night, Mashery has added yet another useful feature based on your feedback!

CORS (Cross Origin Resource Sharing) is a W3C standard that defines how browsers and servers can interact with one another and provides a mechanism for web applications to make requests to a resource in another domain. All major browsers support this standard. Mashery has made it easy to leverage this standard with just a  few button clicks and without requiring changes to your back-end API server. In addition, by using this optional feature available in Mashery, you can offload pre-flight request / response management to Mashery. That is, if a valid pre-flight request comes through, Mashery will prepare an appropriate pre-flight response with the right headers as well as perform the necessary validations on whether the requested method is allowed on the API end-point.

Below is a screen-shot of these new settings that are available while configuring your API end-points

We are pleased to announce the release of the Event Trigger API, a new way to integrate your API related business processes and systems with the Mashery platform.  The Event Trigger API makes it easy to connect these business systems, e.g. a 3rd party CRM product, internal data warehouse or custom billing solution, with the Mashery processes and data that drive your API program.  Whether performing custom validation rules to ensure that developers who are signing up to the portal are desired or appropriate to supplementing developer or application data in the Mashery database with information stored in your own system to simply recording the issuance of new keys for applications in a separate, non-Mashery database, the Event Trigger API is a real-time integration tool, allowing you to both streamline processing by forgoing potentially more complex integration paths as well as to generate a better user experience that works in line with your business.

The Event Trigger API is configured through the Mashery Dashboard and authorized individuals pick and chose the business objects of interest and when to receive data and notifications.  There is a simple testing tool that enables you to understand the flow of the data and get you more familiar with the feature.  The API is documented here.  A screenshot of part of the configuration UI is show below.

Please contact support@mashery.com for more information and to have this feature turned on for you.

Mashery is pleased to announce the availability of a new set of reports that enables customers to quantify the volume of data being served through their API program. This represents the latest way that Mashery is supporting the efforts of our customers to widely broadcast the achievements of their API programs to other internal stakeholders and to the broader public audience alike.

I look forward to seeing the exciting new ways that customers seek to define their API achievements using data-oriented definitions. Remember that comparing data quantities hinges on how you define it! For example, the 5 gigabytes (5 x 10^9 bytes) of storage capacity contained within the original iPod was touted as holding “1000 songs in your pocket.”[1] A “Library of Congress” worth of data based on current estimates amounts to 15 terabytes of data (15 x 10^12 bytes).[2]

This new report, entitled Data Served, can be found within the Reports section of the Mashery Administration dashboard and is automatically turned on for all customers.

Below is a screen-shot of the new Data Served report for a selected Package & Plan

Below is a screen-shot of the new Data Served report for a selected API Service

References:

[1] http://support.apple.com/kb/HT1353

[2] http://blogs.loc.gov/digitalpreservation/2012/04/a-library-of-congress-worth-of-data-its-all-in-how-you-define-it/