Packages

What is a package?

Every folder in your API definition is a package.

1
fern/
2
├─ fern.config.json
3
├─ generators.yml
4
└─ definition/ # <------ root package
5
  ├─ api.yml
6
  ├─ imdb.yml
7
  └─ persons/ # <-------- nested package
8
    ├─ director.yml

The generated SDK will match the hierarchy of your API definition.

1
const client = new Client();
2
3
// calling endpoint defined in imdb.yml
4
client.imdb.getRating("goodwill-hunting");
5
6
// calling endpoint defined in persons/director.yml
7
client.persons.director.get("christopher-nolan");

Package configuration

Each package can have a special file called __package__.yml. Just like any other definition file, it can contain imports, types, endpoints, and errors.

Endpoints in __package__.yml will appear at the root of the package. For example, the following generated SDK

1
const client = new Client();
2
3
client.submitRating("goodwill-hunting", 9.5);

would have a fern directory

1
fern/
2
├─ fern.config.json
3
├─ generators.yml
4
└─ definition/
5
  ├─ __package__.yml # <---
6
  └─ api.yml

that contains the following __package__.yml:

1
service:
2
  base-path: ""
3
  auth: true
4
  endpoints:
5
    submitRating:
6
      method: POST
7
      path: "/submit-rating/{movieId}"
8
      path-parameters:
9
        movieId: string
10
      request:
11
        type: double
12
        docs: Rating of the movie

Namespacing

Each package has its own namespace. This means you can reuse type names and error names across packages.

This is useful when versioning your APIs. For example, when you want to increment your API version, you can just copy the existing API to a new package and start making changes. If the new API version reuses certain types or errors, that’s okay because the two APIs live in different packages.

1
fern/
2
├─ fern.config.json
3
├─ generators.yml
4
└─ definition/
5
  ├─ api.yml
6
  └─ imdb/
7
      └─ v1/
8
        └─ movie.yml # type names can overlap with v2/movie.yml
9
      └─ v2/
10
        └─ movie.yml

Navigation

__package__.yml also allows you to configure the navigation order of your services. This is relevant when you want to control the display of your documentation.

For example, let’s say you have the following Fern Directory:

1
fern/
2
├─ fern.config.json
3
├─ generators.yml
4
└─ definition/
5
  ├─ projects.yml
6
  ├─ roles.yml
7
  ├─ users.yml

Your API will be sorted alphabetically: projects, roles, then users. If you want to control the navigation, you can add a __package__.yml file and configure the order.

1
navigation: 
2
  - users.yml
3
  - roles.yml
4
  - projects.yml

Note the fern directory structure will now look like:

1
fern/
2
├─ fern.config.json
3
├─ generators.yml
4
└─ definition/
5
  ├─ __package__.yml # <------------ New File
6
  ├─ projects.yml
7
  ├─ roles.yml
8
  └─ users.yml