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.

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

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:

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

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.

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.

$	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

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