The blind acceptance of an API’s terms and conditions presents an interesting quandary for anyone running an API program. One could simply take a caveat emptor view and not lose any sleep over whether a consumer reads the small print. However, one could also view incomprehensible terms and conditions as a lost opportunity: If an existing customer disregards the small print, are prospective customers being put off? In this post we’ve put together a practical guide on creating an API platform policy, including what items to include and how to convey the most vital information. By the end of the article you should have an idea of how to present your policy in a digestible way so your customers actually read and understand it, with the goal being to ensure an application developer can move from discovery to development as quickly as possible.
Nearly every API provider publishes one or more legal documents that define the terms and conditions under which their API can be used. These documents can include any of the following:
- Terms of Service;
Legal documents such as these are common in all sectors of technology, and collectively they define a contract between the API provider and consumer, specifying the legal obligations of each upon each other. Whether you sign a piece of paper or simply start using the API, as a consumer you are bound by this legal contract. One could simply say “why bother with contracts”, but this is not a tenable position: The need to define legal contracts for using an API covers a myriad of different subject areas including intellectual property, data protection, regulatory obligation, and of course commercial agreements where access to the API is paid for.
When drafting an API platform policy of your own it’s important to understand that these documents tend to cover several key underlying themes, namely:
- Defining responsibilities;
- Setting expectations;
- Describing good behavior.
Once a clear map of responsibilities is created, the API platform policy should then describe what the API consumer should expect of the API provider. Setting expectations is synonymous with a service-level agreement, but again the goal should be to define it such a way as to make it straightforward for the API consumer to digest. This is almost the most important part of the policy, as the API consumer may need to pass these expectations onto their customers: If an API provider defines the availability of their API as being 99%, for example, this implicitly becomes part of the terms and conditions between the API consumer and their customers.
It would be easy to create a huge compendium of the aspects that API providers should take account of when setting expectations, but a brief list would include:
- Availability of the API;
- Types of support available and their responsiveness (in high-level terms, not email, ‘phone numbers, etc.);
- Access to developer portal, sandbox environments, refresh of authorities and entitlements (API keys, OAuth client IDs, etc.);
- Requirements for certification and on-boarding (screening, compliance checks, certification of implementation, etc.)
- API functionality as referenced in documentation
Now that we know what to expect of the API provider, the final step is to define what is expected of the API consumer. This next part describes what is acceptable and not acceptable behavior, and communicates the actions the API provider might take should these good behaviors not be observed.
Describing Good Behaviors
With a clear picture of responsibilities and expectations, the API provider should then define what their expectation of “good behaviors” are (which may be tied into a commercial agreement with paid-for APIs). Good behaviors fall into two groups: application behavior and consumer behavior. These groups tend to reflect the interest of the application developer and legal team respectively.
Application behavior refers to how a software program that consumes the API is coded to ensure it does not breach what it is responsible for or attempt to exceed expectations. The behavior expected or forced on the application can be manifested in a number of ways:
- Enforcement of rate limits to ensure “bursts” do not exceed a given throughput in a defined period;
- Enforcement of quotas with an upper limit on the number of API calls over a given period;
- Dropping long running HTTP connections or blocking new connections where an upper limit has been breached.
API consumers need to ensure they design and implement their applications to be cognizant of these good behaviors. Without doing so, they run the risk of providing a poor user experience and decreased functionality to the users of their application. Moreover, if an application repeatedly breaches the good behavior policy then access to the API could be rescinded completely.
Final Thoughts on Platform Policy
Making an API policy interesting, relevant and to the point is a goal that any API architect or product manager should take seriously. Whilst the lawyers will always have their day in wrapping up your policy in jargon, you should actively shape the output, and ensure the key points are easy to digest, understand and act upon. If possible reflect the following in your policy:
- Produce an accurate summary of the key points of the legal documents, covering responsibilities, expectations and behaviors;
- Ensure the summary is in easily accessible language that anyone can understand (for a great example see the Google Developer Guidelines);
Taking this action can only improve developer experience – a hallmark for quality APIs that are accessible to the developer community. As the API economy continues to grow with increasing competition between different API providers, such an approach can only, prima facie (as the lawyers would say :smirk:) help develop a competitive advantage for your API in the marketplace.