There are some languages in the world that are tough to master and for your average application developer none more so than Legaleze, a language so inaccessible that only a learned few can speak it fluently. The diction and terminology is generally so difficult that most don’t even attempt to learn: When presented with an API’s terms of use or platform policy, most developers simply click ‘I accept’ and get on with coding.

OK, so this description of the language found in legal documents is meant to be tongue in cheek, but it’s amazing how organizations in general expect non-lawyers to make informed decisions on whether or not they can accept lengthy terms of use. Deciphering such documents often involves collaboration between a lawyer and a software developer, which is less than ideal given there is room for error or misinterpretation as one attempts to inform the other (lawyers who are also software specialists being a rare, expensive commodity). There are even websites such as Terms of Service; Didn’t Read dedicated to evaluating the terms of use of major web apps to help users combat what TOSDR calls “the biggest lie on the web.” Failing to digest the small print correctly could result in the organization falling foul of a clause in the terms of use that could be passed on directly to their customers.

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.

Key Themes

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 Use;
• Privacy Policy;
• Terms of Service;
• Cookie Policy (for a developer portal).

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.

Given the realities of legal systems it’s difficult to make these points bubble up to the attention of the developer (as Stripe reflects upon in their terms of use. However, it’s paramount that these themes are drawn out to pique the interest of the API consumer and ensure they’ve either consciously accepted the terms and conditions they are signing up to, or have drawn it to the attention of their organization’s legal team.

Defining Responsibilities

Almost all legal documents start with a definition of the responsibilities of all the parties involved in the contract and API platform policies are no exception. A traditional legal contract will contain several sentences with prescriptive definitions of terms like ‘You’ and ‘Us’: If possible, keep these terms in core legal documentation but summarize the key points with sufficient brevity to keep the reader’s interest. The level of brevity required is demonstrated well by Instagram, who use a numbered General Terms section to clarify for the API consumer what they absolutely need to know whilst keeping the more lengthy terms of use in the background. It’s important to “dumb down” the key points in this way to highlight the responsibilities that have the greatest impact on the API consumer. As we’ve seen before, Instagram actively pursues taking down consumers who breach their terms, therefore they phrase their agreement in plain English to ensure consumers know exactly what they can and cannot do with the Instagram API.

Setting Expectations

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

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.

Consumer Behavior

While application behavior can be coded, ensuring good API consumer behavior is a bit more tricky: It involves a human being making a decision about how they are going to use an API that may not concur with the terms of use defined by the API provider. Consumer behavior generally (but not always) comes as a result of a business decision and should not be made in isolation by a software developer but in conjunction with the product’s legal and commercial teams.

The majority of humans are generally subjective in their points of view, so it helps if API providers are prescriptive in what an API consumer can and can’t do with their API with a summarized list in the manner of Stripe. API providers can take breaches of their terms of use very seriously, as with the 9 month take down of Politwoops by Twitter showed: It’s therefore important for both the provider and the consumer to be 100% clear on both the definition of consumer behavior and the consequences of not observing it.

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;
• Clearly explain the mitigations or consequences that will be apparent should any terms of use be breached.

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.