API Contracts

I manage the API contracts that drive your digital supply chain, factory floor, and distribution channels, helping you achieve your business goals with greater velocity and consistency--API contracts are the human and machine readable artifacts that shape the business and technology of your enterprise operations in a digital age.

Raw Materials

Suppliers

Factories

Distribution

Retail

• Internal APIs

• 3rd-Party Cloud APIs
• 3rd-Party On-Premise APIs

• Source Control
• Pipelines
• Gateways

• Portals
• Repositories

• Desktop Applications
• Web Applications
• Mobile Applications
• Artificial Intelligence

There are numerous perspectives that you should be considering when it comes to optimizing API operations--you can use the following select boxes to adjust your API contract to match your perspective of why APIs matter, and how API contracts can help guide and govern what matters most to you and your business today.

Technical Stakeholder Business Stakeholder Executive Leader

Further Along in Journey Picking Up Momentum Just Getting Started

Producing Consuming End-User

3rd-Party 1st-Party Internal

Cloud On-Premise Open-Source Inner-Source

APIs

Contract Policies

These are all of the common policies we focus on API Contracts, reflecting the baseline seen across leading public API producers across most business sectors--which you can filter based upon your perspective above. These policies are intended to govern API operations in a consistent and repeatable way from both the business and technical aspects of operations.

Repository

The GitHub, GitLab, or BitBucket repository for an API, providing the single source of truth for the API contract, OpenAPI, and other artifacts, as well as the road map, change log, support, feedback, and other elements of a repository.

YES NO

Repositories:

Require each API contract possess a GitHub, GitLab, or BitBucket repository.

Teams:

Require that API contract management is controlled using Git teams.

Artifacts:

Require the APIs.json contract, OpenAPI, and other artifacts are stored in repository.

README:

Require that each API contract repository has a dedicated README.

No Details

Metadata

Unique identifier, name, description, tags, and other metadata for the contract that defines the purpose of the API Contract, and how it benefits API producer and consumers, establishing the base of the agreement.

YES NO

Unique Identifiers:

Providing unique identifiers for API contracts, as well as the APIs that are indexed as part of a contract, providing a key reference.

Name:

Providing a clear, descriptive, and concise name for each API contract, as well as the APIs it contains, properly defining the scope.

Descriptions:

Providing a robust description of the API contract, as well as each API it contains, providing my context for stakeholders of the contract.

Images:

Including images as part of the metadata for your APIs helps make APIs more visible as part of portals, documentation, and other resources.

Tags:

Tags provide a bounded context for your APIs, providing keywords that help organize APIs by domains, and make them more discoverable.

No Details

Use Cases

The who, what, how, and why of producing an API, making sure all of the known use cases are accurately described and kept up to date, then used to ensure each API is delivering what is expected with each use case.

YES NO

Who:

Who is using an API, focusing on the people who will be putting an API to work in their applications.

What:

What will consumers be building with the resources and capabilities being made available via APIs.

How:

How will consumers be putting API resources and capabilities, getting into the details of programming languages and frameworks.

Why:

What are the reasons an API consumer will be putting APIs to work in their applications and integrations as part of their business.

No Details

Documentation

The human-readable HTML, Markdown, or PDF representation of the technical surface area of each API, providing path, methods, summaries, description, examples, and the other resources consumers will need.

YES NO

Paths:

Providing simple, clean, and intuitive paths as part of the documentation being published for consumers to use.

Request Bodies:

Including details and examples regarding the request bodies being submitted for POST, PUT, and other possible methods.

Responses:

Making sure there is a complete example for each API response in documentation, including happy and unhappy responses.

Schema:

Documenting all of the schema which are used as part of request bodies and responses, providing JSON SChema representations of each.

No Details

OpenAPI

A machine-readable OpenAPI using the most recent version of the API specification, describing the surface area of each API, which is then used to render the human-readable documentation, and other supporting elements.

YES NO

OpenAPI Version:

Requiring there is the latest version of OpenAPI available.

Title:

Requiring the info title property meets the policy standards.

Description:

Requiring the info description property meets the policy standards.

Contact:

Requiring that there is a contact included in the OpenAPI info.

License:

Requiring the info license property meets the policy standards.

OpenAPI Terms of Service:

Requiring the info terms of service property meets the policy standards.

Version:

Requiring the info version property meets the policy standards.

Operation Summary:

Requiring that all operational summaries meets the policy standards.

Operation Description:

Requiring that all operational descriptions meets the policy standards.

Operation Tags:

Requiring that all operational tags meets the policy standards.

Operation Security:

Requiring that all operational security meets the policy standards.

Request Bodies:

Requiring that all operational request bodies meets the policy standards.

Request Bodies Schema:

Requiring that all operational request body schema meets the policy standards.

Parameter In:

Requiring that all operational parameters in property meets the policy standards.

Parameter Names:

Requiring that all operational parameters names meets the policy standards.

Parameter Descriptions:

Requiring that all operational parameters descriptions meets the policy standards.

Parameter Schema:

Requiring that all operational parameters schema meets the policy standards.

Response 2xx:

Requiring that all 2xx responses meets the policy standards.

Response 2xx Schema:

Requiring that all 2xx responses schema meets the policy standards.

Response 2xx Examples:

Requiring that all 2xx response examples meets the policy standards.

Response 4xx:

Requiring that all 4xx responses meets the policy standards.

Response 4xx Schema:

Requiring that all 4xx response schema meets the policy standards.

Response 4xx Examples:

Requiring that all 4xx response examples meets the policy standards.

Response 5xx:

Requiring that all 5xx responses meets the policy standards.

Response 5xx Schema:

Requiring that all 5xx response schema meets the policy standards.

Response 5xx Examples:

Requiring that all 5xx response examples meets the policy standards.

Schema Type:

Requiring that all schema type meets the policy standards.

Schema Descriptions:

Requiring that all schema descriptions meets the policy standards.

Schema Property Names:

Requiring that all schema property names meets the policy standards.

Schema Property Descriptions:

Requiring that all schema property descriptions meets the policy standards.

Schema Property Enums:

Requiring that all schema property enums meets the policy standards.

Schema Property Required:

Requiring that all schema property required meets the policy standards.

Schema Property Shapes:

Requiring that all schema property shapes meets the policy standards.

No Details

Getting Started

The step by step walk-through for new API consumers, ensuring they have exactly what is needed to discover and onboard, but also help make sure the getting started steps are as simple, plain language, and easy to follow.

YES NO

Documentation:

Provide a link and description to your API documentation, providing the entry point for API consumers to begin learning about what your API does.

Authentication:

Needs description.

SDKs:

Provide a link and description of where API consumers can learn more about authentication and how it will work when they use an API.

No Details

Login

Providing a way to login and gain access to an API, offering a simple human-readable URL to the login page, or ideally some sort of automated login process that allows access with as few clicks and steps as possible.

YES NO

No Details

Plans

Plans are all about being explicit and transparent with all of the access for an API, breaking down the tiers, rate limits, features, and pricing that is available for API consumers, standardizing the business of APIs.

YES NO

Metrics:

Providing details regarding the metrics available for each plan, outlining how the usage of digital resources and capabilities are being measured.

Rate Limits:

Providing details of rate limits being applied as part of each plan, and what is available to consumers as part of their application usage.

Regions:

Providing regional details available for access API resources and capabilities in different geographical regions as part of API plan usage.

Elements:

Offering other elements or features of an API that are included or not included within a plan to help API consumers understand scope of what is available.

No Details

Authentication

Distilling down the authentication required for an API, outlining API keys required, JWT, OAuth, and other authentication types, providing details on how to obtain accounts, tokens, and anything needed for accessing APIs.

YES NO

Keys:

Require the API key usage meets standards set by authentication policies.

JWT:

Require JWT usage meets standards set by authentication policies.

OAuth:

Require that OAuth usage meets standards set by authentication policies.

Scopes:

Require Oauth scopes meets standards set by authentication policies.

No Details

Versioning

Providing semantic or date-based versioning for an API, offering an overview of what is adopted for an API and why, letting consumers know that their is change management in place and how they can tune into communication.

YES NO

Semantic Versioning:

Require usage of major, minor, and patch Semantic Versioning for managing change.

Date-Based Versioning:

Require usage of date-base versioning for managing change.

No Details

Road Map

Providing a simple yet informative look at what features are being planned for future releases of an API, or even sharing that nothing is currently being planned--just providing any insight on what the future will hold.

YES NO

Date:

The date for the proposed API change in the road map.

Title:

The title for the proposed API change in the road map.

Details:

The description for the proposed API change in the road map.

Road Map Version:

The version of the proposed API change in the road map.

No Details

Change Log

Having a change log of anything added, updated, or removed for an API, but also for the other operational and supporting resources for each API, ensuring there is a easy to read manifest of what has happened for an API.

YES NO

Date:

The date of the change that was made to an API.

Title:

The title of the change that was made to an API.

Details:

The description of the change that was made to an API.

Version:

The version of the change that was made to an API.

No Details

SDKs

Offering software development kits, or SDKs for an API, handling authentication, and working across all available API operations in a variety of relevant programming languages to the targeted consumers of an API.

YES NO

JavaScript:

Require a JavaScript client SDK available with each API.

PHP:

Require a PHP client SDK available with each API.

Java:

Require a Java client SDK available with each API.

Go:

Require a Go client SDK available with each API.

CSharp:

Require a CSharp client SDK available with each API.

No Details

Status

Making an API status page, monitoring reports, or other real-time updates regarding the uptime and availability of an API, providing current, but also the historical status of API, helping maintain trust with API consumers.

YES NO

Status Dashboard:

Require a link to as well as results from a status dashboard for an API.

Status History:

Require a link to as well as results from a status history for an API.

No Details

Performance

Publishing details regarding the performance of APIs, complimenting status and uptime information, but drilling into more detail regarding speed, latency, and other performance related metrics that matter to API consumers.

YES NO

Latency:

Requiring details regarding the regular latency for each available API.

Response Time:

Requiring details regarding the regular response time for each available API.

No Details

Security

Providing an overview of security practices for an API, including details covered as part of authentication and access management, but also security testing and certifications that matter to API consumers.

YES NO

Authentication:

Require details regarding how authentication is handled as part of API security.

Testing:

Require that security testing has occurred and publishing results for API security.

No Details

Support

Outline what support is available for API consumers, including email, tickets, forums, and paid support services, making it easy for API consumers to understand how they can get the help they need across APIs.

YES NO

Support Email:

Require that an API is supported using email.

Support Tickets:

Require that an API is supported using a ticketing system.

Support Issues:

Require that an API is supported using Git issues.

No Details

Feedback

Providing feedback on the business and technical details of each API contract, helping facilitate feedback from consumers and other stakeholders, but also from the learnings across other private and public API contracts in use.

YES NO

Feedback Email:

Allow for teams to receive feedback on API contracts via email.

Feedback Issues:

Allow for teams to receive feedback on API contracts via Git issue.

No Details

Terms of Service

Making sure that terms of service are front and center for API consumers, ensuring that the legal side of using API resources and capabilities in applications and integrations by 3rd party consumers is covered.

YES NO

No Details

Privacy Policy

Publishing a privacy policy covering the producer and consumers of an API, as well as end-users of applications, adding to the legal resources that are available to 3rd party developers when putting APIs to work.

YES NO

No Details

Licensing

Publishing a license for the interface, client code, server code, and data to ensure consumers understand the legal implications of using the API, code, and data into their own applications and integrations.

YES NO

No Details

Policies

Providing the machine-readable policies that link machine-readable rules with the business reasons why we are governing an API and the operations around it, helping organize rules based upon the business reasoning behind them.

YES NO

No Details

Rules

Providing the machine-readable rules used to govern an API that can be used as part of pipelines or other automation to lint an API, making sure the baseline for each API and the operations around it are available as part of the contract.

YES NO

No Details

The policies are derived from the profiling of hundreds of public APIs across different business sectors, considering the common properties present as part of publicly available API portals. There are other policies that can be considered, but this represents the common set of policies present for 3rd party public APis.

Contract Support

Each API Evangelist Contract comes with a base of support services by default, helping provide a platform for each API contract to exist, while making sure questions are answered, feedback is gathered, and guidance is available for teams who are producing APIs.

Source of Truth

Establishing a single GitHub, GitLab, or BitBucket repository to manage the contract, providing a single source of truth when it comes to the API contract, as well as all of its properties supporting the evolution of the API at the center.

YES NO

Questions

Empowering teams to ask questions via issue or discussion via Git repository, or directly via email about the API lifecycle, governance, as well as the business or technical elements of producing an API for wider consumption.

YES NO

Feedback

Providing feedback on the business and technical details of each API contract, helping facilitate feedback from consumers and other stakeholders, but also from the learnings across other private and public API contracts in use.

YES NO

Guidance

Ensuring there is guidance for teams throughout their API journey, providing simple text and video guidance for all of the topics business and engineering teams will encounter as part of their regular work to produce consistent APis.

YES NO

Provenance

Helping curate the provenance of each API contract as it evolves over time, documenting change, and cataloging the reviews, validation, certification, and conversation that occurs as each API moves forward and matures over time.

YES NO

Contract support services can be augmented and enhanced with strategy services, but should provide the baseline support that most teams producing APIs will need within the enterprise. API contract support services will ensure that teams don't lose their way during their API journey, and are able to move forward confidently with work producing APIs.

Contract Services

Each API contract provides access to a suite of tactical services that will help establish and evolve API contracts, keeping teams who are producing APIs moving forward and keeping the proper amount of attention on the business and technical details of an API contract. Contract services are designed to help keep API producers moving at just the right speed to stay aligned with business goals, but also the expectations that are set with consumers.

Mapping

Mapping the landscape of APIs, defining one or many contracts that already exist, helping to better understand the scope of existing API operations, and organize based upon the bounded context that matters most to leadership.

YES NO

Creation

The creation of APIs.json business, OpenAPI technical, and other properties of a contract that are machine-readable, helping lay the groundwork for your API contracts, then helping guide you in refining and evolving them over time.

YES NO

Review

Providing reviews of API contracts to identify existing patterns in use across API operations, then also providing feedback on anti-patterns, as well as additional patterns that could be applied to help improve API operations.

YES NO

Certification

Certification of the properties of a contract, ensuring that they exist and are up to standards, and that individual API operations are accessible and are aligned with business use cases and are acceptable with contract schema.

YES NO

Mediation

Provide mediation services when there are disagreements between owners and stakeholders producing APIs, as well as between producers and consumers over the business or technical details of an API, helping establish alignment.

YES NO

Nudges

Weekly nudges on an agreed upon day regarding any questions, feedback, and changes being proposed by both API producer or consumer, helping keep the API lifecycle moving forward and maintain agreed upon levels of activity.

YES NO

These services are designed to implemented tactically by a single team, line of business, or API, as well as be aligned with wider API strategy services that help provide the scaffolding for an API governance program, a common and agreed upon API lifecycle, as well as the other standardized building blocks of enterprise API operations. Services can be scaled to meet the needs across many different teams or lines of business.

Initiate Contract

As an API producer we welcome you to initiate a contract for your APIs. If you are unsure of where to start, begin with a single contract and we can advise you from there. If you have question, go ahead an initiate, and we can answer your questions as we progress.

Your Name

Your Email

Your Role

Your Company

Other Info

This form will send an email directly to Kin Lane, with all of the information you've provided, and you should hear back within a day about how we can help you manage your API contract(s) across your public and private APIs.

APIs are powering your business today, and we want to make sure you have the contracts in place that keep your business moving into the future.