In order to give you better service we use cookies. By continuing to use our website, you agree to the use of cookies as described in our Cookie Policy

Are you a Kong Gateway user? We'd love your feedback. Take the Survey

Kong Logo
  • Get Started
  • Products
    • kong-enterprise Kong Enterprise
      • Kong Enterprise

        End-to-end connectivity platform

      • Kong Mesh

        Universal service mesh

      • Kong Studio

        Empower your developers

      • Dev Portal

        Accelerate innovation

      • Kong Manager

        Manage all your services

      • Kong Immunity

        Autonomously identify issues

      • Kong for Kubernetes

        Native Kubernetes Ingress Controller

      • Enterprise Plugins

        Instantly implement policies

      • Kong Vitals

        Monitor your Kong Enterprise

      • Get Started
    • Built on an Open-source Foundation
      • kong-gateway Kong Gateway

        API Gateway

      • kuma Kuma

        Service Mesh

      • insomnia Insomnia

        API Design and Testing

      • Install
    • Kubernetes & Subscriptions
      • Kubernetes Ingress Controller

        Ingress and CRDs

      • Subscriptions

        Kong Gateway and Enterprise features

  • Solutions
    • Use Cases
      • Decentralize Apps and Services

        Accelerate your journey into microservices

      • Secure and Govern APIs

        Empower teams to provide security, governance and compliance

      • Create a Developer Platform

        Rapidly design, publish and consume APIs and services

    • Deployment Patterns
      • API Gateway

        Take control of your microservices with the world’s most popular API gateway

      • Kubernetes

        Own your Kubernetes cluster by using Kong as an Ingress Controller

      • Service Mesh

        Build, secure and observe your modern Service Mesh

  • Plugins
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Docs
    • Documentation
      • Kong Gateway
      • Kong Enterprise
      • Kong Mesh
      • Kong Studio
      • Plugins Hub
  • Resources
    • Learning
      • eBooks
      • Webinars
      • Briefs
      • Blog
    • Community
      • Community
      • Kong Nation
      • Kong Summit
      • GitHub
    • Support
      • Enterprise Support Portal
      • FAQS
      • Kong Professional Services
      • Kong University
  • Company
    • About
    • Customers
    • Investors
    • Careers
    • Partners
    • Press
    • Contact
  • Get Started
Kong Gateway Kong Enterprise Kong Studio Getting Started
Edit this Page
Documentation

Best Practices for API Design

  • 1.0.x (latest)
Careful! You are browsing documentation for an outdated version of Kong . Go here to browse the documentation for the latest version.

Introduction

Staying up to date on the latest trends in API design helps you create APIs that are simple for application developers to learn and use successfully.

Here you will learn how API design benefits from the following guidelines:

  • Design first, then build
  • Ease of understanding and usage
  • Thorough documentation

Design first, then build

Before you write a line of code, write down what your API shape should be, how you expect information to pass through it, and how it should respond to the information (including success and error-handling). This plan will provide you with an early opportunity to get feedback and to collaborate with others about the experience of using your API without accruing technical debt.

Your design should refer to a single source of truth in a portable format such as OpenAPI / AsyncAPI, and it should indicate the transfer protocols format (e.g., GraphQL, Protobuf). That way, your design is easy to maintain, share, and save in source control since it’s in a text file that others can comment on and audit without switching context.

When designing before you build, Kong Studio can help your team collaborate with Import from Git and synchronize changes through the Git Sync feature. Kong Studio can also help you discover issues quickly through linting and previewing.

Ease of understanding and usage

For an API to be easy to read and use, it should conform to best practices based on its type. For example, the best practices for REST APIs1 include building around resources and conforming to the HTTP semantics for methods. Not all of those help with a GraphQL API, so there are separate best practices for GraphQL.

Kong Studio can help conform to either set of best practices, as it understands both REST and GraphQL through OpenAPI. It can generate requests from either type directly from the OpenAPI specification.

Thorough documentation

Building your API so that it’s easy to read and use is only the first step. Now that you’ve created an intuitive API, it’s time to consider the presentation to your developer audience. Generating OpenAPI, SDKs, or any other form of reference documentation may not be enough for developers to fully understand and benefit from the value of your API. For guidance, your developers benefit from examples of usage and methods to integrate with other tools, in what we call behavioral documentation.

Good Behavioral Documentation consists of the following attributes:

  • Examples of Requests / Responses
  • Guides on how to perform common actions
  • Guides on how to integrate with another popular tool
  • Guides on how to build a basically functional service or tool

Stripe Docs provide an exceptional model of reference documentation and behavioral documentation. Note that reference documentation can also have behavioral components intermixed—it’s not strictly one or the other. Developers are most likely to learn, experiment, and succeed when you provide a strong combination of both.

Kong Studio can help you provide thorough documentation by visualizing what your final output looks like and by enabling you to see changes in real time using the Preview feature.

Footnotes

1: This is a great resource, and the comments on the pages often provide additional color, alternative use-cases, and thoughtful counter-arguments or exceptions. return

  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Gateway
    • Kong Enterprise
    • Get Started
    • Subscriptions
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2021