Today we rolled out yet another update to the Mashery Local product. Mashery Local 2.1 includes a roll-up of several Traffic Manager features such as improved CORS support,end-point wild-card parameters and OAuth accelerator improvements while continuing to ensure that the product functions well in the context of Mashery's unique hybrid architecture. For details on these features , please see the respective blog entries.

Based on feedback and to be in line with the OAuth 2.0 specification, Mashery has made a small but important change to the way I/O Docs makes requests for OAuth access tokens. 

Who's affected: Depending on your OAuth 2 access token provider's implementation, you may need to modify it to receive the token request credentials in the Authorization header. This is the compliant way to receive credentials and will successfully work with I/O Docs. For customers using Mashery OAuth Accelerator, no change is required.

Issue: I/O Docs was incorrectly passing credentials in the POST body (URL encoded) and the Header. This is not in compliance of the spec and will  result in a 400 (invalid_request) in the response from the authorization server. 

Whats changed: I/O Docs will send the client ID/secret pair in the Authorization header. This change is necessary to comply with OAuth2 spec RFC, ttp://tools.ietf.org/html/rfc6749#section-5.2

Necessary Action:Modify your authorization code to receive the token request credentials in the Authorization header. This is the compliant way to receive credentials and will successfully work with I/O Docs

If you're impacted by this change, we appreciate your time to make the minor modification on your end. We'll continue to make improvements to I/O Docs based on your feedback. 

I/O docs (PHP version) supports Markdown syntax to be used within the description properties at the API, method, and parameter level. There are however some limitations with using markdown in I/O Docs JSON based definitions.

I/O Docs Markdown Known Limitations and Issues

Due to the nature of the I/O docs view implementation, the API description supports a subset of the Markdown syntax. Specifically, links and tags that utilize quotes are not supported at the API description level and only supported at the resource level, within the method and parameter descriptions level. For example:

"description": "This is [an example](http://example.com) inline link."

Other limitations

• Links, Images, and Tables are not supported at the API description level (at the top of the page).
• Heading level 2 (H2) renders as a drop-down list when used at the API description level (see image below)
• Bulleted lists render as indented items without bullets.
• Automatic links are not supported; this syntax will not render a link in I/O docs: <http://example.com/>

Markdown uses blank lines to indicate that a "new line" is desired in the resulting HTML. A blank line is any line that looks like a blank line — a line containing nothing but spaces or tabs is considered blank. To represent this Markdown syntax correctly within the I/O docs JSON definition requires adding a "\n" before the markdown in certain cases. For example, the following code will show something as Heading level 1 (H1):

"\n# Level 3 Header"

Level 3 Header

Mashery is pleased to announce the release of Spotlights, a new set of reports that enables our customers to enjoy unprecedented levels of visibility into the performance of their API programs.

The new Spotlights set of reports have been designed to answer a diverse collection of interesting business questions through new data visualizations depicting the behavior of individual developers and the overall API program alike. Customers can find the Spotlights section under the Reports Tab in the API Usage navigation area.

I look forward to seeing the new and exciting ways that our customers gain a competitive advantage by utilizing these data visualizations of their API program data.

The Spotlights report entitled “Historical Call Volume Trends” is designed to provide customers with the tools to identify developers who have:

• an increasing trend of consuming the API data and would be excellent candidates for potential showcasing broadly in future communications
• a decreasing trend to consuming the API data and would represent opportunities for an API program account manager to proactively engage

The Spotlights report entitled “Error Volume Trends” is designed to provide customers with the tools to identify developers who have:

• a trend of unsuccessfully consuming the API data and would benefit from additional guidance or documentation on best practices

The Spotlights report entitled “Historical API Usage Limit Enforcement Trends” is designed to provide customers with the tools to identify developers who have:

• a trend of exceeding the current API data consumption limits applied by the API provider with regard to the daily quota of requests allowed (Quota) or to the allowed calls-per-second (QPS).

The Spotlights report entitled “Hourly Call Volume Trends” is designed to provide customers with the tools to identify:

• trends in the overall hourly demand pattern of the API program with respect to the distribution of successful or unsuccessful consumption of API data

Mashery is pleased to announce the availability of a new report that provides customers program-wide visibility of API call volumes across their entire product offering. 

This new report, entitled API Call Volume by Service and Type, can be found in the Reports section of the Mashery Administration dashboard within the summary page, and is automatically turned on for all customers. Customers using the API Packager feature would see a similar report entitled API Call Volume by Package and Type.

This release represents the latest way that Mashery is providing guidance to our customers to identify interesting program components that would be great candidates for additional review time of the associated business and technical metrics.

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

This report also makes use of the common additional drilldown into each API Call type:

Mashery Local 2.2,  with new and improved tools for Mashery Local Operations and Support staff is now available ! With this release, tools are available to assist with debugging any issues with API calls as they flow between client application, Mashery Local and your API back-end system . In addition, tools that help gather diagnostics and address Mashery Local configuration issues are also available

The tool to introspect API call data is enabled via a simple control on the Mashery Local Cluster Manager UI interface. For the duration this is enabled, Mashery Local will produce verbose call data logs that can be written out to a local location or a shared NFS location. The tool has an auto shut-off capability when the timer expires.

Each API call produces a directory that is stamped with the Mashery Message ID – a globally unique identifier for each call that flows through Mashery. If you are not familiar with using Mashery Message ID in your request /response headers to create a golden thread between your partners, Mashery and your back-end systems, see this post. Using this GUID, your support staff can quickly drill down to the call logs for the problem API call.

For each API call’s verbose data logs, 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 into call data helps address questions such as whether the issue is due to the processors applied or the API back-end system.

Apart from this verbose call data logging facility, this release also includes a debug utility made available via a command line console. The debug utility provides several options to the user, some come in handy when you need to gather Mashery Local system health information to diagnose common system configuration errors on Mashery Local. Other options are useful to resolve some issues identified as an outcome of the diagnosis.

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

Mashery is pleased to announce the release of a new set of reports that enables our customers to enjoy new levels of visibility into the API performance benefits provided by our caching feature.

These newest reports are available for all customers and can be found with the Reports tab of the Administration dashboard as follows:
For a selected Package or Service > System Status > Cache

Each of the new reports can also be filtered to a particuilar Package and Plan.

The report entitled “Overall Percentage of Call Responses Served” is designed to provide customers with the tools to quantify the aggregate volume of API calls served from each source: the Mashery Cache vs. the customer’s backend infrastructure a.k.a. the Origin.

The report entitled “Percentage of Call Responses Served” is designed to provide customers with visibility into the trending for the volume of API calls served from each source.

I look forward to seeing the new and exciting ways that our customers further adopt the caching feature to improve their downstream user experience.

New Feature: Chart and Legend InteractivityMashery is pleased to announce the release of a new report drill down feature that will revolutionize the way our customers extract insights from our reporting and analytics offering.

This new enhancement is available for all customers and is applicable throughout the reports portfolio.

Our customers can now drill-down to specific content by either 1) clicking on the legend entry for the interesting content 2) clicking on a data point associated with the interesting content.
If at any time our customer can click the newly visible “Reset Chart” button to return to the original chart state.

See diagram below for additional details.

This reporting and analytics enhancement serves as the latest way that Mashery is committed to delivering a steady stream of innovations to our customers.

We’re pleased to announce the release of several updates to the ever popular I/O Docs tool including

• SOAP support in I/O Docs
• New custom forms engine using Alpaca
• New JSON editor, Ace

SOAP Support in I/O Docs

File this one under "teaching a new dog, old tricks." With I/O Docs support for SOAP APIs, providers can now offer developers a modern tool for a mature protocol. This is especially useful for large enterprises who currently have (or plan to make) their SOAP APIs available but have no easy way to help their developers explore their service. SOAP based web services certainly have their challenges but learning and discovery of the API shouldn’t be one of them. If you happen to be using SOAP to expose webservices, in just a few clicks, you can bring the simplicity and power of I/O Docs to your developer audience.

I/O Docs will parse and convert an imported WSDL (XML) into JSON format to generate interactive documentation for both secure and non-secure APIs. Developers simply enter parameter values and make live API calls. SOAP support goes beyond just building an interactive UI based on the schema, types, and bindings; when a developer clicks “Try it”, I/O Docs retranslates the JSON objects into XML based SOAP calls and displays the requests/response data, making the learning experience for the developer instant and enjoyable - surely easier than having to generate a third-party SOAP client that generates business-object interfaces and network stubs. By bringing a new school experience to an old school model, I/O Docs makes it easy for enterprise customers to take advantage of the tool of choice for interactive API documentation.

If you’ve already enabled I/O Docs in the Mashery portal, setting up I/O Docs for SOAP APIs requires no additional configuration or curation of the original definition; the WSDL provides everything I/O Docs needs in order to power itself.

1. From the I/O Docs dashboard, import a WSDL by pointing I/O Docs to a URL

2. Save the translated definition

3. Make SOAP API calls from I/O Docs

I/O Docs WSDL requirements

As with all things SOAP, things can sometimes get complicated quickly. We did our best to adopt common practices in our translation of WS-Security, Schemas, and Types, but there are  a few “rules of the road” when using WSDLs to generate I/O Docs; we've written them up and made them available here. Though this is by no means the final definitive list, the guide will help make the journey as smooth as possible.
 

Schemas and Forms - I/O Docs revs up it’s forms engine

I/O Docs definition now includes request schemas to describe the data accepted by API methods (for PUT and POST). Though schemas are not required by I/O Docs, they can be used to do some pretty neat things as shown in the example below. I/O Docs has borrowed the schemas concept from Google Discovery Document Format  which in turn is based on JSON Schema V3 for its schema representations. I/O Docs now also makes use of Alpaca jQuery form to provide custom forms based on JSON schema.

Combining the use of schemas with Alpaca* engine, you can now create custom form fields to send JSON objects in the form post. This obviates the need to embed JSON in a text area (yuk!), and removes the potential for other not-so-desired side-effects (e.g, url-encoded POST); the plain truth of it is, I/O Docs becomes easier to use for your developer audience while staying true to your API. 

The brief example below uses a schema definition, “Widget”, to generate a custom form request for the “InsertWidget” method.

A the top of the I/O Doc definition, a schemas object is created and within it, the Widget is defined.

"schemas":{
      "Widget":{
         "id":"Widget",
         "type":"object",
         "properties":{
            "name":{
               "type":"string",
               "description":"The name of this Widget."
            },
            "description":{
               "type":"string",
               "description":"A full length description of this Widget."
            }
         }
      }
   }

...in the resources section of the I/O Doc definition, the “Widget” schema is referenced in the method request.

"resources":{
      "Test Endpoint":{
         "methods":{
            "insertWidget":{
               "description":"",
               "httpMethod":"POST",
               "path":"/post",
               "request":{
                  "$ref":"Widget"
               }
            }
         }
      }
   }

The definition is rendered in I/O Docs as followed. Note that the request body paramater of insertWidget is JSON .

Ace JSON Editor

We’ve replaced the I/O Docs editable textarea field with the widely used Ace** editor to deliver full blown code editing functionality including: In-line JSON validation, code folding, syntax highlighting and a whole lot more.  Thanks to the folks at Cloud9 IDE, Mozilla, and all the developers who contributed to building this amazing editor! Here's a screenshot of Ace in I/O Docs

* Alpaca is a community-led open-source project licensed under Apache 2.0.
** The Ace source code is hosted on GitHub and released under the BSD license ‐ very simple and friendly to all kinds of projects, whether open-source or not.

As you are probably aware, OpenSSL released a security advisory yesterday, April 7th, regarding a serious vulnerability nicknamed “Heartbleed”, which impacted a large number of Internet applications and services. The vulnerability allowed an attacker to steal private certificate keys or even gain access to data in memory of a vulnerable SSL server. Mashery, along with its service providers, has addressed this vulnerability and believes it has been resolved.

Prior to resolution, some Mashery customers may have been affected by this vulnerability though there is no log information associated with this exploit that allows Mashery to determine whether any systems were compromised. Customers exposed to the vulnerability included only those on the Mashery Enterprise network utilizing SSL certs to enforce secure communication between their consumers and Mashery SaaS systems. API traffic for Customers on Mashery's Premium Network and API traffic managed via Mashery Local were not exposed to the threat.

Mashery’s Enterprise network utilizes Amazon Web Services, which incorporates Elastic Load Balancers (ELBs) in traffic management. Amazon has issued statements today containing information on the vulnerabilities with ELBs as well as other Amazon offerings along with resolution information. According to their release, all AWS regions utilizing ELBs have been patched. Mashery is continuing to monitor any additional information released by Amazon and additional, related threats.

If you are using Mashery’s Enterprise SaaS edition with SSL transport on API traffic (SSL on the Mashery developer portal is not in scope for this vulnerability), we recommend that you replace your SSL certificate. To begin this process, please open a support ticket with Mashery via self service portal (mashery.com/selfservice) or by emailing support@mashery.com and our support group will walk you through the process.

We at Mashery continue to take security very seriously and are taking all measures possible to address this. Mashery continues to evaluate this vulnerability to determine if any additional systems were at risk during the vulnerability period. Mashery will provide any updates as they are available. Thank you for your patience on this issue. As always, please feel free to reach out to us if you have any additional questions or concerns.

While the actual threat window has been closed, we have been working actively with our customers to rotate SSL certificates. We are also continuing to follow through with assessing any additional risks and remediation steps as necessary. 

As a reminder, if you are deployed on the Mashery Enterprise network and have not already done so, please open a support case to begin the process of swapping out your SSL certificates.  If you have questions or concerns or are not sure if you are using our Enterprise network, please contact us at support@mashery.com

It has been a week since the initial reports of CVE-2014-0160, aka the Heartbleed exploit.  Over this time we have been working closely with our customers to assist those who might have been exposed to this vulnerability in performing their own risk assessments based on their knowledge of their own systems and the information that we have provided. The purpose of this coordinated investigation is to allow customers to determine their level of risk and execute any required mitigation steps.

For Mashery, this has meant reviewing our infrastructure and connection points with customers to provide that all appropriate systems have been patched and any necessary certificates and credentials have been rotated as security best practices demand. We have sent out multiple communications directly to customers as they relate to specific threat vectors  and continue to work with them to install new customer certificates as they come in.

The task of evaluating the risk not only to Mashery but also to our customers has been one that we have not taken lightly. We will continue to stay on top of this issue and message out as appropriate.  Please contact us at support@mashery.com should you have any questions or feedback about this process.

Mashery is pleased to announce the release of an new expanded set of reports that enables our customers to enjoy new levels of visibility into the API performance benefits provided by our caching feature.

Now, API administrators can drill-down into their technical asset hierarchy and visualize the percentage of traffic that is delivering responses from Mashery's Cache feature or from their backend technical infrastructure. Once filtered, the data table transitions to an interactive data visualization for further investigation and insight generation.

Cache utilization reports are available for all customers and can be found within the Reports tab of the Administration dashboard as follows:
For a selected Package or Service > System Status > Cache

Please see the screenshots below depicting this exciting new feature:

We are excited to announce that with last night’s release, Mashery has included additional caching optimizations around handling If-Modified-Since header. This HTTP header can be quite useful to improve response times and reduce traffic bandwidth between client applications and your API back-end systems. The way If-Modified-Since header works is very simple. It simply allows any system that honors this header to evaluate if content has been modified since the date specified in the request. If content has not been modified since the date, the system responds back with “304 Not Modified” without sending back the entire payload. This way client applications can reliably use local caches to fulfill responses, speeden up response times and avoid unnecessary response payloads getting downloaded from API back-end systems

To understand how this works and to benefit from this feature, you must first enable Mashery cache for the API end-point.

If an application sends a request with If-Modified-Since header against that end-point, Traffic Manager will first check if a valid response can be delivered from cache. If Mashery cache has a valid response, Traffic Manager will evaluate if the cached response needs to be revalidated against API back-end system based on additional directives such as “max-age”, “s-maxage”, "must-revalidate”. If revalidation is not called for, Traffic Manager will return back with a “304 Not Modified” response avoiding request / response roundtrip to the API back-end system. Even if revalidation is called for, Traffic Manager performs additional optimizations and converts the request to a conditional request to minimize traffic bandwidth to your API back-end system. If the API back-end system responds back with “304 Not Modified” in this case, Traffic Manager will deliver the valid response from Mashery cache. If the API back-end system responds back with a “200 OK”,  response is delivered as usual to the client application and updated in cache.
 

OpenSSL has released a new exploit notification (CVE-2014-0224), and as with all such exploits, Mashery is working to identify and patch any systems that might be subject to this exploit.

Unlike the previous HeartBleed exploits, we believe this vulnerability did not expose any customer certificate or private key information to an attacker. Whereas, with HeartBleed, customers were required to rotate out their Certificates and generate them with new Private Keys, in this case there is no action needed on the part of Mashery Customers.

We will be providing updates as more information becomes available on this or other security related topics.

Please don't hesitate to contact us via support@mashery.com or via the self service portal (mashery.com/selfservice) should you have any further questions.

Best, Scott

================================
Scott Farnsworth
Director, Technical Services  |  Mashery, Inc.

We are pleased to announce the general availability of enhanced Cache Reporting, the latest addition to the Reporting & Analytics provided within the API administration dashboard.

API administrators can now drill-down deep into their API programs and visualize the percentage of API responses that are being delivered from the Mashery cache feature or from their backend infrastructures.

Now, API administrators can proactively identify opportunities to unload non-transactional API traffic from consuming their backend capacity and instead leverage Intel Mashery’s globally distributed API distribution network. Customers delivering static data or rich-media content like videos, music, articles, etc…, who have optimally configured their use of the Mashery cache feature would see improvements to their API response times and, for any mobile-deployed products, a seemingly “faster” end-user application experience as data is transferred in less time.

The new reports provide a "birds-eye view" across Packages, Plans, API’s, Endpoints, Methods and developers. Each drill-down perspective contains a pair of reports for an overall assessment and a time-trended assessment of how the Mashery cache feature is being utilized. A key benefit of this deep visibility into cache utilization is the potential for our customers to influence internal discussions on how to improve the backend infrastructure with respect to the indicated traffic trends for APIs, endpoints, and methods.

When filtered, the report data tables transition smoothly to become an interactive data visualization for further inspection and insight generation.

The new reports are available for all customers who have the cache feature enabled and can be found within the Reports tab of the Administration dashboard at the following location: For a selected Package or Service > System Status > Cache.

Please see the screenshots below depicting this exciting new feature in action!

We launched a useful little feature recently that allows monitoring of rate limit consumption.  This is a feature that needs to be be toggled on via a UI option to be available. When this feature is toggled on, all responses returned from that end-point will automatically include a bunch of Mashery generated headers that display information such as allotted QPS, allotted quota, current QPS, current quota as well as time duration left to quota reset. Useful for e.g. if a developer runs out of allotted daily quota and needs to know when the next call can be made against that end-point.

For e.g. with this option enabled, if a developer is making a call using a package key for a package plan that has method level limits specified, below are some headers that would be included into the response by Mashery
X-Plan-QPS-Allotted
X-Plan-QPS-Current
X-PlanMethod-QPS-Allotted 
X-PlanMethod-QPS-Current 
X-Plan-Quota-Allotted
X-Plan-Quota-Current
X-PlanMethod-Quota-Allotted
X-PlanMethod-Quota-Current

Here’s the screenshot of where you would enable this option via Endpoint -> Properties page ( Include rate limit data in response headers)

We added a bunch of important improvements to Mashery Traffic Manager recently that really rounds off our support for a very important industry standard CORS. Hope you find them useful !

• If Allow requests from any domain is set to No on the Dashboard then:
  • The API administrator can specify a comma separated "List of domains allowed". The requests made from domains that are not in the list are denied.
  • To allow for more flexibility, API administrator can also select if "Sub-domain matching allowed" is Yes.  By default, exact domain matching process is followed. 
    • In case of an exact domain match, for e.g. if http://abc.com, is specified in the “List of domains allowed”, only requests for http://abc.com are allowed.
    • In case of a sub-domain match, for example, if http://abc.com is specified in the “List of domains allowed” on the Dashboard, requests coming from http://abc.com, http://xyz.abc.com and http://xxx.abc.com are accepted as valid and allowed through
    • Note that in either of the above cases, http://abc.com, https://abc.com, and http://abc.com:8080 are not considered identical and are never matched
• CORS specification does not allow any custom header to be processed by the browser client application except if the server explicitly white-lists those headers via Access-Control-Expose-Headers. With the "List of headers to expose" field, API administrator can white-list the headers  that Traffic Manager will add to Access-Control-Expose-Header in the response.
• API administrator can specify a comma separated "List of headers allowed". These are used to validate against values in Access-Control-Request_Header and determine if the request can be allowed through or not. If allowed, corresponding headers are added to Access-Control-Allow-Header back in the response. If this field is left empty, any incoming header is allowed – this is to maintain backward compatibility
• API administrator can specify whether cookies are allowed for the CORS requests or not. By default, cookies are not allowed. If cookies are allowed, Access-Control-Allow-Credentials is set to true on the preflight response and CORS response.
• To facilitate debugging scenarios for CORS request and response, any selected Mashery specific debug headers are white-listed via Access-Control-Expose-Headers so that the client application can process the response appropriately. Specifically if Include X-Mashery-Responder Header in Response, and Include X-Mashery-Message-ID Header in Response are selected on the end-point settings in the dashboard, these will be added to Access-Control-Expose-Headers list
• Even in the case of error responses, CORS specific headers are added in the response. This allows the client application to read and process the right error message   
• Even if pre-flight request fails, it is returned with a 200 code but with the right error message  This will ensure that the client application can process and display the appropriate error message on the browser which facilitates better debugging.

A security advisory was released on 09/24/2014 related to a vulnerability, now informally being referred to as Shellshock, that exists in GNU Bash.  For more information about this vulnerability, please refer to CVE-2014-6271 and CVE-2014-7169.  An incident response is in effect and immediate actions have been taken by Intel-Mashery to address this vulnerability.  We will update you with more information as it becomes available.  Please contact support@mashery.com with questions or concerns.

Mashery understands the impact and is working towards building and deploying the patch for Mashery Local 2.2 customers by end of next week. Also Mashery Local is less vulnerable as it sits behind the firewall.

Mashery addressed the SSLv3 vulnerability aka Poodle in our environment within few hours of learning about it on the afternoon of October 14th 2014. After carefully reviewing the likelihood and impact of this vulnerability, we determined the risk to be High, especially as “Poodle” became a widely known vulnerability that could potentially expose our customers’ data. We decided to disable SSLv3 immediately with an option to rollback on a customer case-by-case basis.

Prior to disabling SSLv3, we informed our customers about our decision and made that change (i.e., disabling SSLv3) during our weekly maintenance window (11 PST 11/14/14) on the same day. We also recommended our customers to use TLS 1.0 or above as per the industry best practice. Follow up communications were sent to our customers to keep them abreast on the status of the change.

We did not come across any significant interruptions due to disabling SSLv3 in our own, or our customers’, operations. We made every effort to address customer issues as early as possible. Only a very small number of customers reported issues caused by the necessary change.

As always, customers’ information security has always been one of our top priorities and we will continue to do our part to safeguard customer data.

Please contact customer support at support@mashery.com, Intel Services' Support Portal, or call our toll free number: 888-667-1588. You can also follow our updates on our Twitter stream, @MasheryOps.

For more information about this vulnerability, please refer to http://googleonlinesecurity.blogspot.com/2014/10/this-poodle-bites-exploiting-ssl-30.html.