Gartner Research

A Guidance Framework for Designing a Great Web API

Published: 18 February 2016

ID: G00300000

Analyst(s): Brad Dayley , Gary Olliffe


Web APIs are crucial enablers for reaching new customers through multiple channels, such as cloud, mobile and social applications. This framework provides guidance on new practices for architects designing and delivering Web APIs.

Table Of Contents

Problem Statement

The Gartner Approach

The Guidance Framework

  • Prework: Establish Business Alignment
    • Web and Mobile Enablement for Internal Developers
    • Customer Engagement
    • Business Model Extension
  • Step 1: Create Developer Personas
    • What Are Personas?
    • Good Design Isn't Just for GUIs
    • Why Use Personas in Web API Design?
    • Developers Are Users Too
    • Key Characteristics of Good Developer Personas
  • Step 2: Map Interaction Scenarios
    • Recipe for a Great Scenario
    • Turning Scenarios Into Action
  • Step 3: Design Legal and Technical Contracts
    • Every Web API Needs a Legal Contract
    • Web API Design Culminates in Consumer-Driven Contracts
  • Step 4: Implement Effective and Transparent Governance
    • Versioning Is the Heart of Web API Change
    • Use Roadmaps to Plan for a Predictable Pace of Change
    • Align Stakeholder Objectives With Product Management
  • Step 5: Deliver Great Support
    • Customer Support Is the New Marketing

Great Documentation Is a Minimum Requirement

Maintain Responsiveness and Availability With Web API Performance Monitoring

Risks and Pitfalls

  • Related Guidance

Gartner Recommended Reading

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

Already have a Gartner Account?

Become a client

Learn how to access this content as a Gartner client.