Gartner Research

Designing a Great Web API

Published: 29 January 2013

ID: G00247165

Analyst(s): Eric Knipp


The programmable Web era has arrived. Web APIs are a crucial channel for reaching new customers through multiple channels, such as mobile and social applications. This framework provides guidance on new practices to architects tasked with designing and delivering Web APIs.

Table Of Contents

Summary of Findings

Guidance Context

  • Problem Statement
  • Guidance Applicability
  • Related Guidance

The Gartner Approach

The Guidance Framework

  • Pre-work: Establish Business Alignment
    • Mobile Enablement
    • 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 Road Maps 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

Risks and Pitfalls


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.