What Is an API Reference?

An API reference is the definitive technical guide to your API, documenting every endpoint, parameter, and response code in detail. It's your ultimate source of truth that developers turn to when they need to know exactly how to interact with your API.

In ReadMe, your API reference is an interactive experience where developers can explore your API, make test calls right from the documentation, and see real responses without writing a single line of code.

Why Your API Reference Matters

A well-crafted API reference can:

Reduce support tickets by answering technical questions before they're asked
Speed up developer onboarding by providing clear, accurate implementation guidance
Build developer trust by showing that your API is thoughtfully designed and maintained
Showcase your API's full capabilities so developers discover features they might otherwise miss

Getting Started with Your API Reference

ReadMe offers several ways to create and maintain your API reference, whether you're working with OpenAPI (formerly Swagger) specifications or prefer to build your reference manually.

In This Section

You'll learn how to:

Upload and manage OpenAPI specifications through multiple methods
Work with our API Designer if you don't have an OpenAPI specification
Customize your API reference to match your brand and enhance usability
Create interactive examples that developers can try right in your docs
Keep your reference in sync with your actual API as it evolves

OpenAPI Upload and Management

ReadMe fully supports OpenAPI 3.0, OpenAPI 3.1, and Swagger 2.0 specifications. You can add your API spec to ReadMe in multiple ways:

File upload: Drag and drop your OpenAPI/Swagger JSON or YAML file
URL import: Point ReadMe to where your spec lives online
GitHub/GitLab integration: Connect directly to your GitHub or GitLab repository using bi-directional sync
Command line (rdme): Use our CLI tool for automated workflows, including GitHub Actions
API Sync: Keep your API reference automatically in sync with your codebase

Once uploaded, ReadMe transforms your spec into beautifully formatted, interactive documentation that developers will love.

API Designer

Don't have an OpenAPI specification? No problem! ReadMe's API Designer lets you build your API reference from scratch with an intuitive interface. Document your endpoints, parameters, request bodies, and response objects without needing to write a single line of YAML or JSON.

Updating Request Parameters

Need to update the request parameters for an endpoint? ReadMe gives you several ways to do this depending on how you manage your API reference:

Using the API Designer

If you built your API reference in ReadMe or want to make quick edits:

Navigate to API Reference in your project
Click on the endpoint you want to update
Find the Query Parameters, Path Parameters, or Request Body section
Click the + button to add new parameters, or click an existing parameter to edit its name, type, description, or required status
Save your changes

For a full walkthrough, see API Designer.

Using Your OpenAPI Specification

If you manage your API reference through an OpenAPI (or Swagger) file:

Update the parameters in your OpenAPI specification file (YAML or JSON)
Re-upload the updated file to ReadMe using one of these methods:
- Dashboard: Go to API Reference → API Definitions, click ⋮ on your definition, and select Update OAS File
- CLI: Run rdme openapi upload openapi.yaml --key=$README_API_KEY
- Bi-directional sync: Commit the updated file to your connected repository

ReadMe updates existing pages in place when you re-sync, so your URLs and any hand-written content on the page are preserved. For details, see Re-syncing Your OpenAPI Document.

Editing the OAS File Directly in ReadMe

You can also edit your OpenAPI specification directly in the ReadMe dashboard:

Go to API Reference → API Definitions
Click ⋮ on your definition and select Edit OAS File
Make your parameter changes in the editor
Click Save — ReadMe validates the file before saving

For more on managing your API definitions, see OpenAPI Upload and Management.

Customizing Your API Reference

Make your API reference truly yours with customization options:

Add authentication details and custom headers
Include code samples in multiple programming languages
Organize endpoints into logical groups
Add custom documentation and overviews to each group of endpoints

GraphQL Support

Working with GraphQL? ReadMe offers limited but growing support for GraphQL APIs. You can document your schemas, queries, and mutations to help developers navigate your GraphQL API.

Best Practices for API References

To create an exceptional API reference:

Be complete: Document every endpoint, parameter, and response
Include examples: Show real request/response pairs for common use cases
Explain errors: Document all error codes and how to resolve them
Keep it current: Update documentation whenever your API changes
Test it yourself: Regularly use your own documentation to catch issues