Gartner Research

A Guidance Framework for Designing a Great API


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.

Published: 26 October 2017

ID: G00336152

Analyst(s): Brad Dayley Gary Olliffe

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

Already a Gartner client?

Become a Client

This research is reserved for paying clients. Speak with a Gartner specialist to learn how you can access this research as a client, plus insights, advice and tools to help you achieve your goals.

Contact Information

All fields are required.

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

Experience information technology conferences

Master your role, transform your business and tap into an unsurpassed peer network through our world-leading virtual and in-person conference series.

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