Frequently Asked Questions
Click a question below to view the answer:
- What data is collected by Mashery on each proxied API call?
- What options do we have when it comes to securing access to our Mashery-powered developer portal?
- How do I change the permission level of a user of our Mashery-powered developer portal?
- How do I adjust or exempt a user's QPS/Rate Limits?
- Is there a way we can upload images and other files to be included in the "custom pages"?
- Can I use an IFrame within a portal page to embed existing content that I have?
- What tools do you recommend for creating API documentation?
- I'd like to temporarily prevent a user of my API from having access to it. Is there an easy way for me to do this?
- What do you recommend for including code snippets in a portal page?
- We want to put in security measures so that the only people who can access our APIs is Mashery i.e. avoid people calling us directly. Have you solved this problem with other partners? If so, any recommendations?
- We would like Mashery to block access to our Mashery-powered developer portal from our competitor. Can this be done?
- I want to have control of the CSS file associated with my Mashery-powered developer portal. What options do I have?
- When you issue new API access credentials to a developer, can you send the registration info to a RESTful interface?
- It seems that getting access to the credentials required to access an API proxied by Mashery is a two stage process. First a new developer signs up for access to the Mashery-powered developer portal and then registers for API access credentials. Why are these separate?
- How can I ensure that a widget utilizing a particular API key is not installed on an unauthorized website?
What data is collected by Mashery on each proxied API call?
We collect the following data for each API call we proxy:
- Traditional Apache-style HTTP request log entry.
- The complete inbound HTTP message. This includes all headers, HTTP POST Method bodies, etc. In other words, everything that the user's code sent when making the API call.
- A log of changes we make to the call (if any) before passing it along to the API endpoint. This might include things like swapping credentials, adding/stripping headers, etc.
- A list of diagnostic information regarding the request our server makes to the endpoint. When we receive that response, we have access to the following bits of information:
- Effective URL. The URL we make the request to, including query string parameters (if any).
- HTTP Code. The last HTTP response code received from the request we make.
- File Time. Remote time of the retrieved document/response. Often not available (thus logged as -1), but we save it if we get it.
- Total Time. Total transaction time in seconds for the request/response.
- Name Lookup Time. Time in seconds until name resolving was complete.
- Connect Time. Time in seconds it took to establish the connection.
- Pre-Transfer Time. Time in seconds from the beginning of the connection until just before the response transfer begins.
- Start Transfer Time. Time in seconds until the first byte is about to be transferred.
- Redirect Time. Time in seconds of all redirection steps (if any) before the final transaction begins.
- Size Upload. Total number of bytes sent in our request.
- Size Download. Total number of bytes received.
- Header Size. Total size of all headers received.
- The complete body of the response received by the endpoint.
- The length of the processing time from the moment we received the request to the moment we return a response.
The inbound and outbound HTTP messages can be filtered prior to logging. For example, if an API request/response has binary data, we drop that before logging the data by default.
What options do we have when it comes to securing access to the developer portal?
Most of our customers view releasing their APIs as a very "public" act by its very nature and are not very concerned about the security of their developer portal. However, we do have customers that require sign-on for viewing any page other than their developer portal home page. We even have customers who have completely locked-down their sites. We will implement you most anywhere on that spectrum you require. Also ANY page that you create can be withheld from view without proper login authentication; i.e., there can be totally public pages, pages that require developer login and pages restricted only to Admin view. Any files that are uploaded as well that you may choose to have available on your site can follow the same authentication paradigm.
How do I change the permission level of a user of our Mashery-powered developer portal?
The way it works in our system today is that first a user registers for an account. Once registered, he/she will receive a confirmation e-mail. In the email is a "confirm" link which when clicked causes the new user account to be activated. Once that user is in the system and his/her account is active, a portal Admin can go to the "Add User Permissions" screen (http://your company name.mashery.com/admin-area/permissions-add) and edit the user's permission level.
How do I adjust or exempt a user's QPS/Rate Limits?
Adjustments to an individual user's Queries per second or Rate Limit are enacted on the Edit API User page. There are two possible ways to reach this page. If you are using the Mashery Powered Portal and know the user information surrounding the account you seek (last name, email address, screen name, username) you can go to the Users tab and use the search box with the appropriate search type selected. Once the account is returned click the display name. This will bring you to the Edit API User page, from there click on the API Key you are looking to adjust.
If you are not using a Mashery Powered portal, are adding users via the Mashery API or only have the API key you would like to adjust then the Edit API User page can be reach through the APIS tab on the main navigation. If you have multiple API Services configured you will see a list of the API Services along with a link to view the API users. If you have only one API Service configured then you will be taken to the list of users by default. Use the search box to find the key in question. Click the returned key link to reach the Edit API User page.
Once on the Edit API User page there are two text boxes that will allow you to override the default rate limit or QPS limit. Below those text boxes are two check boxes that will allow you to exempt the the user from rate and QPS limits. Please note that they will be subject to the aggregate QPS limits set for your API Service.
Is there a way we can upload images and other files to be included in Custom Pages or Documentation.
Yes, click on the "Insert Image or File" button in the toolbar of the Content Management System. This will bring up a dialogue where you can upload a file or choose a previously uploaded file.
Can I use an IFrame within a portal page to embed existing content that I have?
Yes. IFrames work just fine within a portal page and is the recommended way to embed your existing content into a Mashery-powered developer portal. You'll need to set up some CSS to customize the look & feel of the IFrame. The only catch is that you need to insert the IFrame using DOM, not document.write, for it to work in Firefox.
What tools do you recommend for creating API documentation?
Most of our customers use HomeSite and Dreamweaver to code up their pages and cut and paste them into the Mashery-powered portal. The main point to note is that cutting and pasting clean xHTML is very easy and flexible so choose a tool that can generate clean xHTML. We do not recommend using "save as HTML" in MS WORD for example as it generates a lot of additional characters that conflict with the content management functionality of the Mashery-powered portal. For an introduction to xHTML, see this site.
I'd like to temporarily prevent a user of my API from having access to it. Is there an easy way for me to do this?
Yes. In the dashboard of your Mashery-powered developer portal, under the APIs tab, you'll see a list of your APIs. For the API in question click the List API Users link. Find the user in question and click them. Under the Status dropdown select inactive. An inactive user will not be allowed to access your API. When you want to grant them access again, change their status to active.
What do you recommend for including code snippets in a portal page?
With the introduction of our new CMS in June we have added a tool for this. While editing a page click on the "Insert Code Block" button on the toolbar. You can then select the type of code you are adding and have the option to include line numbers. The code snippet will automatically be formatted according to the selected language.
We want to put in security measures so that the only people who can access our APIs is Mashery i.e. avoid people calling us directly. Have you solved this problem with other partners? If so, any recommendations?
This can be accomplished in two manners. Both have advantages and disadvantages.
Option 1 - IP restriction (firewall level)
We give you a list of IP addresses that are going to be calling your API and you add them to your firewall as the only IPs from which requests are allowed. Depending on whether you are using our CDN solution or not this would mean somewhere between 3-15 IP addresses in total. We've done this for a handful of customers. Advantage is it's pretty secure but not 100% bullet proof. Disadvantage is that if one of our machines change (as they will over time as we add more servers) we have to co-ordinate the IP change with you.
Option 2 - HTTP Authentication (webserver level)
As the API request passes through us, we add an HTTP authentication header including a username/password known only to us and you. You configure your webserver to only allow authenticated requests to your API. Advantage of this is it requires less maintenance as once its setup it should not change even if we change our server IPs. Very slight disadvantage is that HTTP Authentication credentials are base64 encoded so in theory they could be spoofed and decoded. The likelihood of this is extremely low given all the other information that would need to be known.
We would recommend starting with the latter approach i.e. HTTP Authentication. It's simple, very secure and easily maintained. It's easy to switch to IP restriction at a later stage if required. This is what the vast majority of our customers have done.
We would like Mashery to block access to our Mashery-powered developer portal from our competitor. Can this be done?
We can block access to your Mashery-powered developer portal by individual IP, range of IP and/or a combination of the two. The difficulty with trying to block a domain is that in most cases, there is no reliable way to determine if an IP originated from a particular domain. Even reverse DNS does not provide reliable information.
I want to have control of the CSS file associated with my Mashery-powered developer portal. What options do I have?
In the dashboard, under Settings/Portal Setup, there are two fields that are relevant here.
The Custom CSS File URL points to the CSS file that will be used for your developer portal. You can have this point to a CSS file on your server and have complete control over your theme.
The Inline CSS field allows you to add CSS that will be appended to the CSS file that is associated with the portal. This is intended to be a temporary placeholder for quickly trying things out. You should move any CSS rules here to the main CSS file when you want to save them permanently.
You have to look at the source in order to see the context in which the classes and IDs are implemented. You can use a tool to view the source or the DOM tree in order to manipulate the CSS effectively. More specific rules take precedence over general rules, and some of the base CSS rules use two or three levels of specificity. In order to override many rules set by the Mashery base CSS, you must see the parent elements of the element you want to target. If you do not know what this means, you can learn all about CSS at HTML Dog.
If you wish to create a theme yourself, we recommend that you use the theme-template. Keep in mind that there are some base Mashery CSS rules that are applied to your portal. Every single class and ID in the theme stylesheets are not included because typically we don't manipulate every class and ID. Documenting the entire framework inside a stylesheet would be overkill and there would be a ton of noise to signal. The most commonly used classes/elements are listed inside the theme-template, and for a typical developer portal some of these are not even used.
When you issue new API access credentials to a developer, can you send the registration info to a RESTful interface?
Yes. One of the mechanisms some of our customers use is to provide us with an API on their end which we call to send them registration data. Depending on the specifics and your contracted service level this could entail additional expense to implement.
It seems that getting access to the credentials required to access an API proxied by Mashery is a two stage process. First a new developer signs up for access to the Mashery-powered developer portal and then registers for API access credentials. Why are these separate?
The reason this is a two-stage process is because some of our customers want to apply certain business rules to the credential provisioning process. It’s also often the case that a customer will want to make their Mashery-powered developer portal public before they are ready to make their API public. So for many reasons it makes sense to have a logical separation of these two events.
How can I ensure that a widget utilizing a particular API key is not installed on an unauthorized website?
On the API Key profile page we now have a 'Required Referrers" option which will allow you to specifically designate which domains are able to send traffic for a specified API key.