Mashery Support Portal Developer Blog

A feature some customers have been requesting is to provide some basic API analytics that their developers could use directly.  We've responded and are pleased to announce the release of the Developer Analytics feature has been made available to all customers today.  With this feature, developers will be able to understand their usage trends of your APIs. 

In this initial release, we're providing call volume, methods utilized, error rates and a quota progress bar.  Developer feedback has been positive as this gives them insight into their usage of your API without requiring any work on their part.  No need to set up traffic monitors on other websites that introduce performance latency.  And no need to install any tracking code on their backends.  Our beta customers have liked it because it's another tool that brings developers to their developer website and provides good utility to developers that they'll appreciate.

The feature is optional.  Please contact our support team and they'll be happy to turn it on for your Developer Portal.

Feedback is always welcome!

We are happy to announce the release of our new Developer Class feature in the Developer Portal! This new feature allows our customers to segment their developers on any number of factors and then manage their access limits by class.  Additionally, once your keys are grouped into a class, you may also completely disable access to an entire class at the click of a button.  This is especially useful in periods where you are over capacity and you wish to give your most critical applications as much capacity as possible.

You may segment your developers in a number of ways.  Two examples being:

• By strategic importance – you have developers internally using your API, strategic partners using your APIs, and a public access for anyone for free.
• Premium support – some users get access for free, others pay for additional call volume.

Lets walk through an example – here is a screen showing three classes – Internal, Partner, and Public.  Each class can have settings such as:

• Name and description
• Which API services to include in the class
• The rate and throttle limit.  Remember, rate governs the calls per day, and throttle governs the calls per second.
• Option to allow overrides on the rate and throttle limit.

Once setup, you can manage developers and group them in such classes.  This second screenshot shows a list of keys and what class each key is assigned.  Remember a user could have multiple keys:

That's it!  Once a key is attached to a class, the access limits set on the class will be applied to the key.  No more managing limits at each key level.

Additionally, we have added a number of API methods that allow you to manage developer classes.  The API allows methods to:

• Create a developer class
• Edit settings of a developer class
• Delete a developer class
• Assign user to a developer class
• Block all users from a developer class

If you have questions or need help implementing this feature, please contact our support team.

Regards,

The Mashery Product Team

JSONP, or JSON with Padding, has gained a lot of traction over the past year.  We've had many customers come to us asking about our support of it or even translate their API to create it from other protocols.  As a result, we are happy to announce we've launched some improvements that make our support of JSONP complete.  First, some background.

JSONP provides a means for a web page to access services outside of its domain. Normally, the browser won't allow a web page to issue cross-domain Ajax requests; if you need to asynchronously load some HTML, XML, or JSON data, you're only allowed to access the web server that served your web page. If the requested data comes from another provider, then you will need your web server to proxy such requests.

JSONP takes advantage of the fact that browsers do allow web pages to load JavaScript from other domains. To get data from a service provider that supports JSONP, add a new script tag to your document and set its src attribute to the desired resource URL. The URL will typically include a query string parameter with the name of a JavaScript function that you previously defined. The browser will asynchronously load the referenced JavaScript and execute it. The returned JavaScript consists of an invocation of the function whose name you provided in the requested URL, with the requested JSON data as its only argument.

For example, suppose you passed updateFeed as the name of your callback function. The response might look like this:

updateFeed({"title":"Test Feed","entries":[]})

Given how simple it is to support JSONP and it's usefulness for developers, we think API providers should consider supporting JSONP.  If you already support JSON as a response format, then adding the "P" should be relatively straightforward:

1. Define the query string parameter for the callback function. This should be published with your API documentation.
2. If you find the callback parameter in the query string, change the response content type to JavaScript (e.g., application/javascript) and wrap the JSON response in parentheses preceded by the value of the callback parameter.

The following PHP code snippet illustrates this:

$callback = $_GET['callback'];
if (empty($callback)) {
	header('Content-Type: application/json');
} else {
	header('Content-Type: application/javascript');
	echo $callback . '(';
}

// output JSON response
// ...

if (!empty($callback)) {
	echo ')';
}

The improvements we just launched are around our error handling.  Our Error Sets feature now support JSONP responses so those error responses we generate (e.g. over limit, service unavailable, timeouts) are returned as expected.  In order to set up your endpoint to return JSONP error responses, you need a JSONP-compatible Error Set:

1. In API Settings, select the desired API and click the Errors tab.
2. Create a new Error Set and check Return as JSONP.
3. Set the Error Format to a JavaScript-compatible content type; e.g., application/javascript.
4. Populate the body of each error response with a valid JSON object describing the error condition (the exact structure is up to you).

Next, you need to configure your endpoint:

1. Select the desired endpoint and go to its Properties tab.
2. In the JSONP Settings section specify the Callback Function Parameter. The value of this parameter will be used as the name of the callback function. You may also specify the Default Callback Function Parameter Value in case the caller doesn't provide one.

That's it! Your API consumers can now expect a consistent experience even in cases when an error response is returned by the Mashery service.

Contact us if you would like help getting this configured or if you'd even like to explore having us extend your API to JSONP through our translation services.  If we see enough interest, we may also just build a feature that can extend your JSON API into JSONP API via simple configuration.

Happy New Year everyone! 2010 is primed to be a great year for APIs!  The pundits are highlighting APIs as a key trend in 2010, we have lots of new customers prepping their launches, and we're breaking call volume records every month!

But before we get heads down on 2010, we put together a product briefing page that sums up the enhancements that were made over the past few months.  Have a look to see what new items might be useful to your program!  If you have questions or need help implementing any of them, please contact our support team as usual.

We wish you all growth in 2010. We're excited to be part of your success!

As your own API initiatives have grown and your needs to either extend your Mashery Developer Portal or integrate with your other systems have increased, we found a need to expand our own API to cover your requirements.  As such, we are pleased to announce the release of version 2.0 of the Mashery API!

Version 2.0 is more comprehensive compared to its predecessor in its coverage of Mashery objects.  It also includes a powerful query language, allowing you to easily perform ad hoc queries for objects. The following objects are supported:

1. Members
2. Applications
3. Keys
4. Roles
5. Service Definitions (including cache)

With this release, we have also created a sandbox site for you to use to safely build and test your programs before deploying them to production.

To get started, peruse our comprehensive documentation.  Then, login to this site with the administrative account that you want to own your API keys.  Request new API keys to gain access by registering on our key registration pages.  Note, data access rights are governed by the rights of the account that owns the API key used so consider which accounts you want to have keys. 

Happy New Year everyone!

We're pleased to announce the release of our new Roles based access control capabilities in the Developer Portal! 

It has been interesting to be part of our customers' API programs as they continue to grow and mature.  One clear trend we've seen is that many APIs eventually have both external and internal benefit.  Some customers start with opening external access for app development as the goal and find unexpected valuable internal uses.  For example, we saw a large customer find a sister site had been screen scraping their content, but started using the API as a better way to integrate (rightly so).  They noticed and added a few private data elements for them and drove significant savings in the end.  

Another interesting set of use cases has been private beta programs.  Many times this has been the usual early development phase for a new program.  However, increasingly, we see mature programs extending their API and want to expose their new version or methods to a limited set of beta developers.  Makes total sense. 

One of the features that emerges in each situation is a need to control which content pages users have access to.  You want your new beta only methods to be viewable to beta partners, but nobody else to reduce confusion.  Or you want to have internal documentation pages for your colleagues.  But when you run large communities of developer partners, you need something like Roles to manage the complexity.  This feature will help.

With this release, you will have the ability to create Roles, grant them content access rights, and then group your users into them.  Additionally, we've packaged up a set of Mashery Dashboard Roles that govern which administrative Dashboard tabs your admins have access to.

Here's an example of using Roles for page access control.

Step 1: Create a Role

Step 2: Assign Users to Role

Step 3: Assign content pages to Roles to restrict access

Done!  Now only users within the assigned "Internal Acme" Role will see the page.  The navigation aids and search features of course also adhere to the access rights granted via Roles. 

For the Dashboard Roles that we now support (e.g. Content Manager), we think you'll understand the Role name and the tabs that they have access to pretty quickly. However, if you click into each on the Roles tab in the Dashboard, you'll find a description and what functionality they grant access to.

As always, please let us know what you think!

Wow, it was a busy summer.  We have been adding lots of great new customers and for you old timers, we see really healthy volume growth through a large section of the APIs we service.  We've been bursting through volume records every month!  It's great to see and be part of your success.  

I haven't posted a blog entry for some time, so thought I'd mention a small but nice feature add that was released last night for those customers that use Mashery caching services.  In the past, we fully managed your cache.  If for some reason, you needed to flush your cache, we were happy to provide you this support.  However, immediate self-serve capability was necessary since sometimes, you just need to move faster than we can offer through our support function. Now you can!

Your API administrators may navigate to the API Settings tab in the Dashboard and find the new "Cache" tab.  There's a simple flush button that takes affect within 8 mins. Give it a try and let us have your feedback!

We are pleased to announce a major upgrade to the Developer Management capabilities of the Mashery Developer Portal.  The improvements provide a rich set of new options for how we register your developers, grant them keys and register the applications they build.  Additionally, the User Administration Dashboard has been completely redesigned for usability and improved visibility into your developer community. 

This has been a significant product development undertaking and we'd like to thank all of our great customers that have provided feedback or performed design reviews along the way.  We'd love even more feedback now that you can touch and feel the new functionality, so as usual, post to the forums, send an email to support@mashery.com, or tell your Client Service Manager the good, bad, and (hopefully not) ugly! 

For more information on what was included in this release, please read through the release notes (you must be logged on).

Mashery Clients,

Please be advised that we will have a partial service outage for maintenance purposes this Saturday, July 11th, from 8:00pm to Sunday 2:00am Eastern Daylight Time (EDT).  We will be releasing significant upgrades to the Developer Management aspects of your developer portal.  During this period, the following services will be unavailable:

   1. Developer Portals
   2. Mashery API

Please note, the Mashery API Proxy Service will continue to operate normally and no developer calls to your API will be impacted.  Please contact support@mashery.com with any questions.  During the maintenance window, you may follow our progress with @MasheryOps on Twitter.

More information will be forthcoming about the exciting features that will be released over the weekend.

Thank you,

The Mashery Product Team