API keys (tokens) to track api usage


As many of you know we have a set of public APIs for the Student Web Service. Public APIs mean that access to those APIs do not require any form of authentication. For months now I have seen a trend that has been bothering me. Our percentage of http requests using public apis who are not setting an application useragent or using a X.509 cert has been steady increasing to 14% of all SWS requests. Note that using an application useragent or X.509 cert is not required for public API access but if made available those are two ways that we can track usage. Yes, its a good thing we are seeing more traffic to our Student Web Service however some of us are concerned that we are losing our ability to track usage of our apis and are unable to support those clients properly.

Members of the ROA-technical team recently got together to discuss pros and cons of whether we should require the use of API keys or tokens (keys and tokens are used interchangeably throughout this post) to access our public APIs. Here is what we discussed but did not come to a decision because that was NOT an agenda item for our meeting. Your input to this blog can help influence what future decision we decide to take on this issue.

What is the benefit of including a token?

The benefit of registering for an api key or token is simply better client support and capturing application usage data so that service developers know what services to keep, not keep, make better, or not make better.

What would be some things to think about when implementing the use of an API key/token?

    If implemented:

  • We should only require an API key for public apis. The addition of using a cert and an API key for access to private resources seem overkill.
  • The key should be required to be passed to the api on every request.
  • The api key can be reused among many applications and there is no way to enforce the use of one token per web application. We can however set a policy that a developer keep the token a secret and only uses it for apps written within their department. If we do not set this policy then our application usage tracking data will likely become skewed and unusable.
  • The api key should be embedded in the URI and not in the HTTP header. This makes it easier for users that just want to browse the service in their browser.

Would introducing the requirement for a token be a violation of the contract with developers?

  • The answer is a resounding YES; if we made it mandatory.
  • It was recommended that we make the key/token optional which we all came to agreement on. If you get a token then developers are in a better position to be supported while those who dont are not. This policy can be stated explicitly while developers are registering their application.
  • So does the benefit of requiring an API key (token) outweigh the costs?

    Benefits:

  • Better usage tracking
  • Better client support
  • Costs:

  • Add new features to the UW Web Services Registry to allow for app registrations. This would require some user interface additions and a token/key validation web service.
  • Update documentation and communicate to our clients on our new API key policy
  • Update all web services to accept API keys on every request and validate them
  • Let us know what you think.

    1. #1 by Tom Lewis - February 24th, 2010 at 14:47

      If the costs are not really burdensome, then this sounds like a great approach.

    2. #2 by Scott Stephenson - March 4th, 2010 at 12:14

      I think we should do this. It’s a win-win scenario.

    3. #3 by Gary Prohaska - March 10th, 2010 at 11:57

      Given that the recommendation is for optional use by web service consumers I think this is a valuable change and imo potential benefits outweigh the costs.

      Question: was their any discussion about “how” the api key would be embedded in the URI?

    4. #4 by ttchang - March 10th, 2010 at 15:22

      Good question. No nothing specific in terms of implementation just that we thought it would be best placed in the uri. We figured we should determine if we should make the use of a key part of our WS policy first before we figured out a design.

    1. No trackbacks yet.

    Comments are closed.