Gartner Research

A Guidance Framework for Creating Usable REST API Specifications

Published: 27 August 2019


REST APIs are a key part of modern application and integration architectures, and ease of use is a critical factor in the success of REST APIs. Application technical professionals should use this framework to design specifications for REST APIs that are easy to understand and use.

Included in Full Research

  • 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 Consumer Developers
    • 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
    • Design Security Into the 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: Create 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: Implement and Publish APIs
  • Using REST for Every Interface
  • Creating Too Many Layers of APIs
  • 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


Kevin Matheny

Access Research

Already a Gartner client?

To view this research and much more, become a client.

Speak with a Gartner specialist to learn how you can access peer and practitioner research backed by proprietary data, insights, advice and tools to help you achieve stronger performance.

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

Gartner research: Trusted insight for executives and their teams

What is Gartner research?

Gartner research, which includes in-depth proprietary studies, peer and industry best practices, trend analysis and quantitative modeling, enables us to offer innovative approaches that can help you drive stronger, more sustainable business performance.

Gartner research is unique, thanks to:

Independence and objectivity

Our independence as a research firm enables our experts to provide unbiased advice you can trust.

Actionable insights

Not only is Gartner research unbiased, it also contains key take-aways and recommendations for impactful next steps.

Proprietary methodologies

Our research practices and procedures distill large volumes of data into clear, precise recommendations.

Gartner research is just one of our many offerings.

We provide actionable, objective insight to help organizations make smarter, faster decisions to stay ahead of disruption and accelerate growth.

Tap into our experts

We offer one-on-one guidance tailored to your mission-critical priorities.

Pick the right tools and providers

We work with you to select the best-fit providers and tools, so you avoid the costly repercussions of a poor decision.

Create a network

Connect directly with peers to discuss common issues and initiatives and accelerate, validate and solidify your strategy.

Experience Technical Professionals conferences

Join your peers for the unveiling of the latest insights at Gartner conferences.

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