Gartner Research

A Guidance Framework for Designing a Great API

Published: 26 October 2017

ID: G00336152

Analyst(s): Gary Olliffe , Brad Dayley


APIs are fundamental to effective web/mobile app, microservice and integration architectures in the digital business ecosystem, but API quality determines adoption and success. Technical professionals responsible for creating APIs can use this framework to design APIs that properly fit their needs.

Table Of Contents

Problem Statement

The Gartner Approach

The Guidance Framework

  • 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 Layered/Mediated API Approach to Provide Agility
    • Use a Back End for Front End or App-Specific Approach
    • Use Event-Driven 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

Risks and Pitfalls

  • Related Guidance

Gartner Recommended Reading

©2020 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.

Already have a Gartner Account?

Become a client

Learn how to access this content as a Gartner client.