What is an API Definition?

An API Definition is a document that defines the structure of the API. It includes the endpoints, request and response schemas, and authentication requirements.

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

1openapi: 3.0.2
2tags:
3  - name: pet
4    description: Everything about your Pets
5paths:
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 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:

1asyncapi: 2.0.0
2info:
3  title: Chat server
4  version: 1.0.0
5
6servers:
7  Production:
8    url: chat.com
9    protocol: ws
10
11channels:
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
32components:
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

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:

1types:
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
17service:
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
37errors:
38  MovieDoesNotExistError:
39    status-code: 404
40    type: MovieId

Why create an API Definition ?

Once you have an API definition, Fern will use 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 and ensure they are always up-to-date.

SDKs

Client libraries in multiple languages.

Documentation

A Stripe-like API documentation website.

Postman logo
Postman Collection

A published Postman collection, with example request and responses.

FastAPI logo
Server Boilerplate

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

Built with