What is a Fern Definition?

A Fern Definition is a set of YAML files that describe your API.

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.

Want to use OpenAPI instead? No worries, we support that as well

Fern Definition structure

To initialize a Fern Definition, simply run:

1npm install -g fern-api

2fern init

This will create the following folder structure in your project:

$fern/

>├─ fern.config.json # root-level configuration

>├─ generators.yml # generators you're using

>└─ definition/

>  ├─ api.yml  # API-level configuration

>  └─ imdb.yml # endpoints, types, and errors

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.
1service:

2  auth: false

3  base-path: /movies

4  endpoints:

5    createMovie:

6      docs: Add a movie to the database

7      method: POST

8      path: /create-movie

9      request: CreateMovieRequest

10      response: MovieId

11

12    getMovie:

13      method: GET

14      path: /{movieId}

15      path-parameters:

16        movieId: MovieId

17      response: Movie

18      errors:

19        - NotFoundError

20        - UnauthorizedError

21

22types:

23  Movie:

24    properties:

25      title: string

26      rating:

27        type: double

28        docs: The rating scale from one to five stars

29      id:

30        type: MovieId

31        docs: The unique identifier for a movie

32

33  CreateMovieRequest:

34    properties:

35      title: string

36      rating: double

37

38errors:

39  NotFoundError:

40    http:

41      statusCode: 404

42    type:

43      properties:

44        id: MovieId

45

46  UnauthorizedError:

47    http:

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

Despite being a different format for describing APIs, you are never locked in to Fern. It’s easy to convert your Fern Definition to OpenAPI.