Gartner Research

A Guidance Framework for Designing a Great API

Published: 21 May 2019


APIs are fundamental to effective web/mobile app, microservices and integration architectures in the digital business ecosystem, but API quality determines adoption and success. Application technical professionals responsible for creating APIs use this framework to design APIs that enable success.

Included in Full Research

  • Prework
    • Understand the Purpose, and Establish Business Alignment for the API
  • Step 1: Identify and Engage Your API Consumers
    • Create Developer Personas
    • Map Scenarios of Developer Interaction With APIs
    • Engage API Consumers Throughout the API Life Cycle
  • Step 2: Design Legal and Technical Contracts
    • API Design Culminates in Consumer-Driven Contracts
    • Every Public API Needs a Legal Contract
    • The Technical Contract Is the Heart of the API
  • Step 3: Select Effective API Implementation Approaches
    • Select and Use an API Specification Format and Tools
    • Apply a Mediated API Approach to Provide Agility
    • Use a Back End for Front End or App-Specific Approach
    • Use Event-Based APIs to Optimize Interactions
  • Step 4: Define an Effective API Life Cycle Management Strategy
    • Focus on Transparency and Consistency
    • Treat the API as a Product With Product Management
    • Define a Clear Versioning Strategy
    • Use Roadmaps to Plan for a Predictable Pace of Change
    • Test Your Product Before You Take It to Market
    • Define a Security and Access Strategy
    • Maintain Responsiveness and Availability With Performance Monitoring
    • Identify Key Analytics Metrics
  • Step 5: Deliver Great Developer Support
    • Generate Great Documentation
    • Provide Clear Communication Channels
    • Make the APIs Convenient for Developers to Implement
    • Plan for Developer Administration
  • Follow-Up
    • Apply the API Design to API Implementation
  • Related Guidance


Brad Dayley Gary Olliffe

Access Research

Already a Gartner client?

To view this research and much more, become a client.

Speak with a Gartner specialist to learn how you can access peer and practitioner research backed by proprietary data, insights, advice and tools to help you achieve stronger performance.

By clicking the "Continue" button, you are agreeing to the Gartner Terms of Use and Privacy Policy.

Gartner research: Trusted insight for executives and their teams

What is Gartner research?

Gartner research, which includes in-depth proprietary studies, peer and industry best practices, trend analysis and quantitative modeling, enables us to offer innovative approaches that can help you drive stronger, more sustainable business performance.

Gartner research is unique, thanks to:

Independence and objectivity

Our independence as a research firm enables our experts to provide unbiased advice you can trust.

Actionable insights

Not only is Gartner research unbiased, it also contains key take-aways and recommendations for impactful next steps.

Proprietary methodologies

Our research practices and procedures distill large volumes of data into clear, precise recommendations.

Gartner research is just one of our many offerings.

We provide actionable, objective insight to help organizations make smarter, faster decisions to stay ahead of disruption and accelerate growth.

Tap into our experts

We offer one-on-one guidance tailored to your mission-critical priorities.

Pick the right tools and providers

We work with you to select the best-fit providers and tools, so you avoid the costly repercussions of a poor decision.

Create a network

Connect directly with peers to discuss common issues and initiatives and accelerate, validate and solidify your strategy.

Experience Information Technology conferences

Join your peers for the unveiling of the latest insights at Gartner conferences.

©2022 Gartner, Inc. and/or its affiliates. All rights reserved. Gartner is a registered trademark of Gartner, Inc. and its affiliates. This publication may not be reproduced or distributed in any form without Gartner’s prior written permission. It consists of the opinions of Gartner’s research organization, which should not be construed as statements of fact. While the information contained in this publication has been obtained from sources believed to be reliable, Gartner disclaims all warranties as to the accuracy, completeness or adequacy of such information. Although Gartner research may address legal and financial issues, Gartner does not provide legal or investment advice and its research should not be construed or used as such. Your access and use of this publication are governed by Gartner’s Usage Policy. Gartner prides itself on its reputation for independence and objectivity. Its research is produced independently by its research organization without input or influence from any third party. For further information, see Guiding Principles on Independence and Objectivity.