Mashery Support Portals Developer Blog

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.

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.

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