What is an API definition? | Fern Documentation

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

1 openapi: 3.0.2
2 tags:
3   - name: pet
4     description: Everything about your Pets
5 paths:
6   /pet:
7     post:
8       tags:
9         - pet
10       summary: Add a new pet to the store
11       description: Add a new pet to the store
12       operationId: addPet
13       requestBody:
14         description: Create a new pet in the store
15         required: true
16         content:
17           application/json:
18             schema:
19               $ref: '#/components/schemas/Pet'
20           application/xml:
21             schema:
22               $ref: '#/components/schemas/Pet'
23           application/x-www-form-urlencoded:
24             schema:
25               $ref: '#/components/schemas/Pet'
26       responses:
27         '200':
28           description: Successful operation
29           content:
30             application/xml:
31               schema:
32                 $ref: '#/components/schemas/Pet'
33             application/json:
34               schema:
35                 $ref: '#/components/schemas/Pet'
36         '405':
37           description: Invalid input
38     components:
39       schemas:
40         Pet:
41           required:
42             - name
43             - photoUrls
44           properties:
45             id:
46               type: integer
47               format: int64
48               example: 10
49             name:
50               type: string
51               example: doggie
52             category:
53               $ref: '#/components/schemas/Category'
54             photoUrls:
55               type: array
56               xml:
57                 wrapped: true
58               items:
59                 type: string
60                 xml:
61                   name: photoUrl
62             tags:
63               type: array
64               xml:
65                 wrapped: true
66               items:
67                 $ref: '#/components/schemas/Tag'
68                 xml:
69                   name: tag
70             status:
71               type: string
72               description: pet status in the store
73               enum:
74                 - available
75                 - pending
76                 - sold
77           xml:
78             name: pet
79           type: object

AsyncAPI (WebSocket APIs)

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:

1 asyncapi: 2.0.0
2 info:
3   title: Chat server
4   version: 1.0.0
5 
6 servers:
7   Production:
8     url: chat.com
9     protocol: ws
10 
11 channels:
12   "/application":
13     bindings:
14       ws:
15         query:
16           type: object
17           properties:
18             apiKey:
19               type: string
20               description: The API key for the client
21               minimum: 1
22         bindingVersion: 0.1.0
23     subscribe:
24       operationId: sendMessage
25       message:
26         $ref: '#/components/messages/SendMessage'
27     publish:
28       operationId: receiveMessage
29       message:
30         $ref: '#/components/messages/ReceiveMessage'
31 
32 components:
33   messages:
34     SendMessage:
35       payload:
36         message: string
37     ReceiveMessage:
38       payload:
39         message: string
40         from: 
41           type: string
42           description: The userId for the sender of the message

OpenRPC (JSON-RPC APIs)

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:

1 # yaml-language-server: $schema=https://meta.open-rpc.org/
2 $schema: https://meta.open-rpc.org/
3 openrpc: 1.2.4
4 info:
5   title: Basic Wallet API JSON-RPC Specification
6   description: A simple JSON-RPC API for querying wallet balances.
7   version: 0.0.1
8 servers:
9   - url: https://wallet.example.com/json-rpc
10     name: Mainnet
11 methods:
12   - name: getBalance
13     description: Get the balance of a wallet address.
14     params:
15       - name: address
16         required: true
17         description: The wallet address to query.
18         schema:
19           type: string
20     result:
21       name: balance
22       description: The balance of the wallet address.
23       schema:
24         type: number
25     examples:
26       - name: getBalance example
27         params:
28           - name: address
29             value: "0x1234567890abcdef1234567890abcdef12345678"
30         result:
31           name: balance
32           value: 42.5

gRPC (RPC APIs)

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:

1 syntax = "proto3";
2 
3 package petstore;
4 
5 // The pet store service definition
6 service PetStoreService {
7   // Get a pet by ID
8   rpc GetPet(GetPetRequest) returns (Pet);
9   
10   // Add a new pet to the store
11   rpc AddPet(AddPetRequest) returns (Pet);
12   
13   // List all pets with optional filtering
14   rpc ListPets(ListPetsRequest) returns (ListPetsResponse);
15 }
16 
17 // Request message for getting a pet
18 message GetPetRequest {
19   int64 pet_id = 1;
20 }
21 
22 // Request message for adding a pet
23 message AddPetRequest {
24   string name = 1;
25   string category = 2;
26   repeated string photo_urls = 3;
27   PetStatus status = 4;
28 }
29 
30 // Request message for listing pets
31 message ListPetsRequest {
32   int32 page_size = 1;
33   string page_token = 2;
34   PetStatus status = 3;
35 }
36 
37 // Response message for listing pets
38 message ListPetsResponse {
39   repeated Pet pets = 1;
40   string next_page_token = 2;
41 }
42 
43 // Pet message definition
44 message Pet {
45   int64 id = 1;
46   string name = 2;
47   string category = 3;
48   repeated string photo_urls = 4;
49   PetStatus status = 5;
50 }
51 
52 // Pet status enumeration
53 enum PetStatus {
54   PET_STATUS_UNSPECIFIED = 0;
55   PET_STATUS_AVAILABLE = 1;
56   PET_STATUS_PENDING = 2;
57   PET_STATUS_SOLD = 3;
58 }

Fern Definition (REST, Webhook, & WebSocket APIs)

The Fern Definition is our take on a simpler API definition format. It is designed with best-practices, supports both RESTful and event-driven APIs, and is optimized for SDK generation.

The Fern Definition is inspired from internal API Definition formats built at companies like Amazon, Google, Palantir, Twilio and Stripe. These companies rejected OpenAPI and built their own version.

Check out an example Fern Definition below:

1 types:
2   MovieId: string
3 
4   Movie:
5     properties:
6       id: MovieId
7       title: string
8       rating:
9         type: double
10         docs: The rating scale is one to five stars
11 
12   CreateMovieRequest:
13     properties:
14       title: string
15       rating: double
16 
17 service:
18   auth: false
19   base-path: /movies
20   endpoints:
21     createMovie:
22       docs: Add a movie to the database
23       method: POST
24       path: /create-movie
25       request: CreateMovieRequest
26       response: MovieId
27 
28     getMovie:
29       method: GET
30       path: /{movieId}
31       path-parameters:
32         movieId: MovieId
33       response: Movie
34       errors:
35         - MovieDoesNotExistError
36 
37 errors:
38   MovieDoesNotExistError:
39     status-code: 404
40     type: MovieId

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 Collection

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

Server Boilerplate

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