Getting started

​

Install

npm install -g fern-api

​

The fern/ directory

The fern/ directory contains your API definition. This generally lives in your backend repo, but you can also have an independent repo dedicated to your API (like Raven’s).

In the root of your repo, run:

fern init

This will create the following folder structure in your project:

fern/
├─ fern.config.json # root-level configuration
└─ api/ # your API
  ├─ generators.yml # generators you're using
  └─ definition/
    ├─ api.yml  # API-level configuration
    └─ imdb.yml # endpoints, types, and errors

​

Generating an SDK

To generate SDKs, you can log in with GitHub from the CLI:

fern login

You can add generators using fern add. By default, this will publish your SDK to the Fern npm registry (npm.buildwithfern.com).

fern add fern-typescript-sdk

To generate the TypeScript SDK, run:

fern generate

​

Defining your API

types:
  MovieId: string

  Movie:
    properties:
      id: MovieId
      title: string
      rating:
        type: double
        docs: The rating scale is one to five stars

  CreateMovieRequest:
    properties:
      title: string
      rating: double

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

errors:
  MovieDoesNotExistError:
    status-code: 404
    type: MovieId

Your Fern Definition is a set of YAML files that describe your API. You can learn more about this in the Define your API section.

​

Running the Fern compiler

The Fern compiler takes your Fern Definition and generates useful outputs, like SDKs. You can learn more about configuring outputs in the Compiler section.