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:

1
npm install -g fern-api
2
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.

1
service:
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
22
types:
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
38
errors:
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.