Gartner Research

A Guidance Framework for Creating Usable REST API Specifications

Published: 14 November 2017

ID: G00342305

Analyst(s): Kevin Matheny


APIs are key to successful delivery of loosely coupled, modular architectures. Ease of use is the most important factor driving the success of APIs. Technical professionals responsible for designing API specifications should use this framework to ensure that REST APIs are easy to understand and use.

Table Of Contents

Problem Statement

The Gartner Approach

The Guidance Framework

  • Prework: Define Your API's Context
    • Understand the Business Purpose of Your API
    • Create Consumer Personas and Scenarios
  • Step 1: Establish API Design Guidelines
    • Start by Copying an Existing Set of Guidelines
    • Promote Your Guidelines, and Make Them Easily Accessible
    • Provide an Exception Process to Enable Intentional Variation
    • Keep Design Guidelines Up-to-Date to Ensure Relevance
  • Step 2: Engage API Consumers
    • Determine How You Will Communicate With Your Consumers
    • Create a Regular Cadence for Consumer Feedback
    • Use Low-Fidelity Prototypes to Get High-Level Feedback
    • Use Open-Ended Questions to Increase Your Understanding
  • Step 3: Design Resource Models
    • Start With the Consumer's Perspective on the Domain
    • Identify Your Constraints
    • Create a Composite Resource Model
    • Iterate to Find the Right Granularity
    • Create Multiple APIs to Deal With Incompatible Use Cases
  • Step 4: Design Resource Representations
    • Discover What Data the Consumer Desires
    • Determine What Data Is Available
    • Compare Datasets to Identify Common Elements
    • Name Your Data Elements
    • Use Structure Inside Your Resources to Aid Readability
  • Step 5: Design API Specifications
    • Choose an API Design Tool to Increase Productivity
    • Decide Your Approach to Content Negotiation
    • Determine Your Versioning Strategy
    • Create Your Linking Strategy
  • Follow-Up

Risks and Pitfalls

  • Failing to Engage the Right Consumers
  • Limited Availability of Consumers
  • Skipping Review Steps to Begin Development
  • Strict Enforcement of API Design Guidelines
  • Failure to Follow API Design Guidelines
  • 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.