> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# What is an API definition?

> Describes the contract between the API provider and API consumer

An API definition is a machine-readable specification of your API's structure, including **endpoints**, **request and response schemas**, and **authentication** requirements. Instead of manually keeping SDKs and documentation in sync with API changes, an API definition enables automatic generation of these artifacts.

Fern integrates with several API definition formats:

#### OpenAPI (REST & Webhook APIs)

Formerly known as Swagger, [OpenAPI](https://swagger.io/specification/) is the most popular API definition format.
OpenAPI can be used to document RESTful APIs and is defined in a YAML or JSON file.

Check out an example OpenAPI Specification for the Petstore API [here](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)

```yaml maxLines={0}
openapi: 3.0.2
tags:
  - name: pet
    description: Everything about your Pets
paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '405':
          description: Invalid input
    components:
      schemas:
        Pet:
          required:
            - name
            - photoUrls
          properties:
            id:
              type: integer
              format: int64
              example: 10
            name:
              type: string
              example: doggie
            category:
              $ref: '#/components/schemas/Category'
            photoUrls:
              type: array
              xml:
                wrapped: true
              items:
                type: string
                xml:
                  name: photoUrl
            tags:
              type: array
              xml:
                wrapped: true
              items:
                $ref: '#/components/schemas/Tag'
                xml:
                  name: tag
            status:
              type: string
              description: pet status in the store
              enum:
                - available
                - pending
                - sold
          xml:
            name: pet
          type: object
```

#### AsyncAPI (WebSocket APIs)

[AsyncAPI](https://v2.asyncapi.com/docs) is a specification for defining event-driven APIs. It is used to document APIs that use
WebSockets, MQTT, and other messaging protocols.

Check out an example AsyncAPI spec for a chat application below:

```yaml maxLines={0}
asyncapi: 2.0.0
info:
  title: Chat server
  version: 1.0.0

servers:
  Production:
    url: chat.com
    protocol: ws

channels:
  "/application":
    bindings:
      ws:
        query:
          type: object
          properties:
            apiKey:
              type: string
              description: The API key for the client
              minimum: 1
        bindingVersion: 0.1.0
    subscribe:
      operationId: sendMessage
      message:
        $ref: '#/components/messages/SendMessage'
    publish:
      operationId: receiveMessage
      message:
        $ref: '#/components/messages/ReceiveMessage'

components:
  messages:
    SendMessage:
      payload:
        message: string
    ReceiveMessage:
      payload:
        message: string
        from: 
          type: string
          description: The userId for the sender of the message
```

#### OpenRPC (JSON-RPC APIs)

[OpenRPC](https://open-rpc.org/) is a spec for describing JSON-RPC 2.0 APIs. It enables interactive docs and code generation tooling to the JSON-RPC ecosystem.

Check out an example OpenRPC Specification for a crypto wallet service below:

```yaml maxLines=0
# yaml-language-server: $schema=https://meta.open-rpc.org/
$schema: https://meta.open-rpc.org/
openrpc: 1.2.4
info:
  title: Basic Wallet API JSON-RPC Specification
  description: A simple JSON-RPC API for querying wallet balances.
  version: 0.0.1
servers:
  - url: https://wallet.example.com/json-rpc
    name: Mainnet
methods:
  - name: getBalance
    description: Get the balance of a wallet address.
    params:
      - name: address
        required: true
        description: The wallet address to query.
        schema:
          type: string
    result:
      name: balance
      description: The balance of the wallet address.
      schema:
        type: number
    examples:
      - name: getBalance example
        params:
          - name: address
            value: "0x1234567890abcdef1234567890abcdef12345678"
        result:
          name: balance
          value: 42.5
```

#### gRPC (RPC APIs)

[gRPC](https://grpc.io/) is a modern, open-source RPC framework developed by Google. It uses Protocol Buffers as its interface definition language and supports multiple programming languages with efficient binary serialization.

gRPC APIs are defined using Protocol Buffer (.proto) files that specify services and message types. Check out an example gRPC service definition below:

```proto maxLines={0}
syntax = "proto3";

package petstore;

// The pet store service definition
service PetStoreService {
  // Get a pet by ID
  rpc GetPet(GetPetRequest) returns (Pet);
  
  // Add a new pet to the store
  rpc AddPet(AddPetRequest) returns (Pet);
  
  // List all pets with optional filtering
  rpc ListPets(ListPetsRequest) returns (ListPetsResponse);
}

// Request message for getting a pet
message GetPetRequest {
  int64 pet_id = 1;
}

// Request message for adding a pet
message AddPetRequest {
  string name = 1;
  string category = 2;
  repeated string photo_urls = 3;
  PetStatus status = 4;
}

// Request message for listing pets
message ListPetsRequest {
  int32 page_size = 1;
  string page_token = 2;
  PetStatus status = 3;
}

// Response message for listing pets
message ListPetsResponse {
  repeated Pet pets = 1;
  string next_page_token = 2;
}

// Pet message definition
message Pet {
  int64 id = 1;
  string name = 2;
  string category = 3;
  repeated string photo_urls = 4;
  PetStatus status = 5;
}

// Pet status enumeration
enum PetStatus {
  PET_STATUS_UNSPECIFIED = 0;
  PET_STATUS_AVAILABLE = 1;
  PET_STATUS_PENDING = 2;
  PET_STATUS_SOLD = 3;
}
```

## Why create an API definition?

Once you have an API definition, Fern uses it as an input to generate artifacts
like SDKs and API Reference documentation. Every time you update the API definition,
you can regenerate these artifacts to ensure they are always up-to-date.

#### [SDKs](/learn/sdks/overview/introduction)

Client libraries in multiple languages that automatically stay in sync with your API.

#### [Documentation](/learn/docs/getting-started/overview)

Interactive API docs with code examples and live testing capabilities.

#### [Postman Collection](/learn/docs/integrations/postman)

Ready-to-use collection with pre-filled example requests and responses.

#### [Server Boilerplate](/learn/api-definitions/openapi/frameworks/fastapi)

Pydantic models for FastAPI or controllers for your Spring Boot application.

> Describes the contract between the API provider and API consumer