Packages in Fern Definition

What is a package?

Every folder in your API definition is a package.

$
fern/
>
├─ fern.config.json
>
├─ generators.yml
>
└─ definition/ # <--- root package
>
  ├─ api.yml
>
  ├─ projects.yml
>
  └─ roles/ # <--- nested package
>
    └─ admin.yml

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

1
const client = new Client();
2
3
// calling endpoint defined in projects.yml
4
client.projects.get();
5
6
// calling endpoint defined in roles/admin.yml
7
client.roles.admin.get();

Package configuration

Each package can have a special definition file called __package__.yml. 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.getProjects();

would have a fern/ folder:

$
fern/
>
├─ fern.config.json
>
├─ generators.yml
>
└─ definition/
>
  ├─ __package__.yml
>
  └─ roles.yml

that contains the following __package__.yml:

1
service:
2
  base-path: ""
3
  auth: false
4
  endpoints:
5
    getProjects:
6
      method: GET
7
      path: ""
8
      response: list<Project>

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

$
fern/
>
├─ fern.config.json
>
├─ generators.yml
>
└─ definition/
>
  ├─ api.yml
>
  └─ roles/
>
      └─ v1/
>
        └─ admin.yml # type names can overlap with v2/admin.yml
>
      └─ v2/
>
        └─ admin.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/ folder:

$
fern/
>
├─ fern.config.json
>
├─ generators.yml
>
└─ definition/
>
  ├─ projects.yml
>
  ├─ roles.yml
>
  └─ 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:

$
fern/
>
├─ fern.config.json
>
├─ generators.yml
>
└─ definition/
>
  ├─ __package__.yml # <--- New File
>
  ├─ projects.yml
>
  ├─ roles.yml
>
  └─ users.yml

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