What is a Fern Definition?

A Fern Definition is a set of YAML files that are the single source of truth for your API. You check your Fern Definition into your repo, inside of which describes your API requests, responses, models, paths, methods, errors, and authentication scheme.

Fern Definition structure

To initialize a Fern Definition, simply run:

npm install -g fern-api
fern init

This will create the following folder structure in your project:

Definition file

Each Fern Definition file may define:

• Custom types. Use custom types to build your data model.
• Endpoints. A service is a set of related REST endpoints.
• Errors. An error represents a failed (non-200) response from an endpoint.
• Imports. Use imports to share types across files.

service:
  auth: false
  base-path: /movies
  endpoints:
    createMovie:
      docs: Add a movie to the database
      method: POST
      path: /create-movie
      request: CreateMovieRequest
      response: MovieId
    getMovie:
      method: GET
      path: /{movieId}
      path-parameters:
        movieId: MovieId
      response: Movie
      errors:
        - NotFoundError
        - UnauthorizedError
types:
  Movie:
    properties:
      title: string
      rating:
        type: double
        docs: The rating scale from one to five stars
      id:
        type: MovieId
        docs: The unique identifier for a movie
  CreateMovieRequest:
    properties:
      title: string
      rating: double
errors:
  NotFoundError:
    http:
      statusCode: 404
    type:
      properties:
        id: MovieId
  UnauthorizedError:
    http:
      statusCode: 401

Why another format?

Google built gRPC. Amazon built Smithy. Facebook built GraphQL. Palantir built Conjure. These companies rejected OpenAPI in favor of a more concise API Definition Language.

We built Fern to productize this design and make it accessible to all software companies.