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 integration: Connect directly to your GitHub repository
• Command line (rdme): Use our CLI tool for automated workflows
• 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.

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