Skip to navigation
Overview

What is an API definition?

View as Markdown

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:

Formerly known as Swagger, OpenAPI 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

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 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:

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 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-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 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:

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

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

Documentation

Interactive API docs with code examples and live testing capabilities.

Postman logo
Postman Collection

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

FastAPI logo
Server Boilerplate

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