Skip to content

The Info Object — API Metadata and Contact Information

DodaTech Updated 2026-06-28 5 min read

In this tutorial, you will learn about The Info Object. We cover key concepts, practical examples, and best practices to help you master this topic.

The info object in OpenAPI provides metadata about the API including its title, description, version, terms of service, contact information, and license details.

In this tutorial, you will learn how to populate every field of the info object, how to write effective descriptions, and how to use contact and license information to build developer trust.

What You'll Learn

You will learn the structure of the info object, best practices for writing API descriptions, how to format version strings, and how to provide proper contact and license information.

Why It Matters

The info object is often the first thing developers see when they open your API documentation. A well-written info section sets expectations and builds credibility. A poorly written one creates a negative first impression.

Real-World Use

DodaTech includes detailed info objects in every API spec. The description explains the API purpose, target audience, and key features. Contact information directs developers to the right support channel for each API.

flowchart LR
  A[Info Object] --> B[title]
  A --> C[version]
  A --> D[description]
  A --> E[contact]
  A --> F[license]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Info Object Fields

title is a required string that names the API. It should be clear and specific. Users API is better than Internal API.

version is a required string that identifies the API version. This is the API contract version, not the implementation version. Use simple integers or semantic versioning.

description is an optional but recommended string that explains what the API does. It supports CommonMark markdown.

termsOfService is an optional URL pointing to the API terms of service.

contact is an optional object with name, url, and email fields for API support.

license is an optional object with name and url fields for the API license.

info:
  title: DodaTech Users API
  version: 2.1.0
  description: |
    Comprehensive API for managing user accounts on the DodaTech platform.

    ## Features
    - Create, read, update, and delete users
    - Role-based access control
    - Bulk user operations
    - Audit logging

    ## Authentication
    This API supports Bearer JWT tokens and API key authentication.
    See the Security section for details.

    ## Rate Limits
    Default rate limit is 200 requests per minute.
    Contact support for higher limits.
  termsOfService: https://dodatech.com/terms
  contact:
    name: DodaTech API Support
    url: https://support.dodatech.com
    email: api-support@dodatech.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

Writing Effective Descriptions

The description should answer these questions in order:

  • What does this API do?
  • Who is it for?
  • What are the main features?
  • How do I authenticate?
  • What are the limitations?

Use Markdown for formatting. Keep paragraphs short. Use bullet points for lists. Include links to external guides.

# Good description
info:
  description: |
    The DodaTech Users API provides programmatic access to user account
    management features on the DodaTech platform.

    **Key features:**
    - CRUD operations for user accounts
    - Role and permission management
    - Batch import and export
    - Audit log access

    ## Before you start
    1. [Get an API key](https://dashboard.dodatech.com/keys)
    2. Read the [Quickstart Guide](/docs/quickstart)
    3. Review [Rate Limits](/docs/rate-limits)

# Poor description
info:
  description: Internal API for users.

Version Format

Use a consistent version format. Semantic versioning (1.0.0) is common but simple integers (1) also work. The version in info is separate from URL versioning.

# Semantic versioning
version: 2.1.0

# Simple integer
version: "2"

# Date-based
version: "2026-06-28"

# With pre-release
version: 2.0.0-beta.1

Contact Information

Provide clear contact information so developers know where to get help:

contact:
  name: DodaTech API Support Team
  url: https://support.dodatech.com
  email: api-support@dodatech.com

The name field should identify the team or person responsible. The url should link to a support portal or documentation. The email should go to a monitored inbox, not a personal address.

License Information

Specify the license under which the API is offered:

license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0

# OR for proprietary APIs:
license:
  name: DodaTech Proprietary License
  url: https://dodatech.com/license

Common Mistakes

  1. Generic title — Using API or Internal API as the title. Every API should have a specific, descriptive title.

  2. No description — Leaving the description blank. The description is how developers understand what the API does without reading every endpoint.

  3. Version mismatch — The info version differs from the URL version. Keep them consistent and document the relationship.

  4. No contact information — Not providing a way for developers to reach support. Every API needs a support contact.

  5. Ignoring Markdown — Writing a description as plain text. Markdown makes descriptions more readable and scannable.

Practice Questions

  1. What are the two required fields in the info object?
  2. What information should the description include?
  3. What fields are available in the contact object?
  4. Why is version important in the info object?
  5. How do you format the termsOfService field?

Challenge

Write a complete info object for a payment processing API. Include a detailed description with Markdown formatting, contact information with support URL and email, terms of service URL, Apache 2.0 license, and semantic version 1.0.0.

FAQ

Should the version in info match the URL version?

Not necessarily. The info version is the API contract version. URL versions are routing identifiers. Document the relationship between them in the description.

Can the description include HTML?

Use Markdown, not HTML. Most OpenAPI renderers support CommonMark Markdown. HTML may be stripped or render incorrectly.

Is the license field required?

No, but including it clarifies the terms under which developers can use your API. Public APIs should always include a license.

How long should the description be?

Long enough to explain what the API does and who it is for. Aim for 2-5 paragraphs with bullet points. External guides can provide more detail.

Can I update the version without changing the API?

Yes. Version bumps for documentation-only changes are acceptable. Use patch version bumps for minor documentation clarifications.

Mini Project

Audit the info objects of five public APIs (choose well-known APIs). Compare their info object quality. List three best practices you observe and three common deficiencies. Apply the best practices to write an improved info object for one of the APIs.

What's Next

In the next lesson, you will learn the servers object and how to define API base URLs, environments, and server variables.

← Previous OpenAPI Document Structure — Root Object and Top-Level Fields Next → The Servers Object — Defining API Base URLs and Environments

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Openapi Spec