Beliebte Suchanfragen

Cloud Native



Agile Methoden



Charge your APIs Volume 12: Fern - Streamlining REST API Development 🌿

9.8.2023 | 4 minutes of reading time

In our previous blog posts, we delved into the world of API description languages, exploring TypeSpec and Taxi language. Thanks to my colleague Ralf Westbrock today we're turning our attention to Fern, a toolkit designed to streamline the process of building REST APIs. We'll examine how Fern can be used to build APIs based on data models described by the tool itself and how these models can be transformed into an OpenAPI description and even more. We'll continue with our retail example for consistency.

Introducing Fern

Fern is a toolkit designed to simplify the process of building REST APIs. It provides a CLI to streamline the process of creating and deploying APIs based the Fern definition within an API Operations pipeline.

Building APIs with Fern

To start anew in the retail domain, we utilise Fern's specific folder structure designed for this area. All you need to do is type fern init. For the first time you have to register an account. This command not only creates a new repository but also sets up the initial API. By doing so, it automatically generates a predefined folder structure for us.

2└── fern
3    ├── api
4    │   ├── definition
5    │   │   ├── api.yml
6    │   │   └── imdb.yml
7    │   └── generators.yml
8    └── fern.config.json

As we aim to outline the Customer API, we'll use Fern's definition framework, examining the imdb.yaml file for guidance. This YAML definition file is composed of three components:

  • Custom Types, which describe the data model,
  • Services, which encapsulate related REST endpoints,
  • Errors, which detail potential failure responses from the endpoints.
1# yaml-language-server: $schema=
4  auth: false
5  base-path: /customers
6  endpoints:
7    getCustomer:
8      docs: Retrieve a customer based on the ID
9      method: GET
10      path: /{id}
11      path-parameters:
12        id: CustomerId
13      response: Customer
14      errors:
15        - CustomerDoesNotExistError
16      examples:
17        # Success response
18        - path-parameters:
19            id: tt0111161
20          response:
21            body:
22              id: tt0111161
23              firstName: Hank
24              lastName: Henderson
25              email:
26              phoneNumber: 555-555-5555
27        # Error response
28        - path-parameters:
29            id: tt1234
30          response:
31            error: CustomerDoesNotExistError
32            body: tt1234
35  CustomerId:
36    type: string
37    docs: The unique identifier for a customer
39  Customer:
40    properties:
41      id: CustomerId
42      firstName: string
43      lastName: string
44      email: string
45      phoneNumber: string
48  CustomerDoesNotExistError:
49    status-code: 404
50    type: CustomerId

Beyond the precise model and endpoint descriptions, api.yaml also supports global configuration. This not only covers the API's name and high-level documentation, but also features like authentication and headers that apply across the entire API.

From Fern description to OpenAPI and more

Having developed an API description for the customer domain, our attention now shifts back to the command-line interface (CLI). Our next task is to generate OpenAPI definitions from these descriptions. However, the CLI's built-in compiler is capable of much more. In fact, we can configure this compiler using another YAML file.

The configuration is carried out using generators.yml. During initialization, this file is pre-populated with two generator configurations: Typescript Node SDK and OpenAPI. Aside from other SDK generators for languages such as Java, Go, Python, and certain frameworks, it also allows us to generate Postman Collections. An example of what this configuration might look like is as follows.

1default-group: local
3  local:
4    generators:
5      - name: fernapi/fern-openapi
6        version: 0.0.28
7        output:
8          location: local-file-system
9          path: ../../generated/openapi
10      - name: fernapi/fern-postman
11        version: 0.0.44
12        output:
13          location: local-file-system
14          path: ../../generated/postman
15      - name: fernapi/fern-java-spring
16        version: 0.3.7
17        output:
18          location: local-file-system
19          path: ../../generated/java-spring

By using the fern generate command, we can kick off the creation of individual artifacts. This triggers various generators to begin their operations in the cloud. Alternatively, if you prefer to run this process locally, you can do so using Docker and the --local parameter.

1❯ fern generate
2[api]: fernapi/fern-openapi Downloaded to /Users/daniel/_new_ideas/fern-playground/retail/generated/openapi
3[api]: fernapi/fern-postman Downloaded to /Users/daniel/_new_ideas/fern-playground/retail/generated/postman
4[api]: fernapi/fern-java-spring Downloaded to /Users/daniel/_new_ideas/fern-playground/retail/generated/java-spring
6│ ✓  fernapi/fern-openapi
7│ ✓  fernapi/fern-postman
8│ ✓  fernapi/fern-java-spring


Fern is a powerful CLI for building only REST APIs at the moment. Its support for data model descriptions and OpenAPI transformations make it a valuable tool for any API developer. Whether you're building a retail API or any other kind of API, Fern can help you design, implement, and maintain your APIs with precision and ease.

As with the other tools we've seen over the last weeks, the power of describing data models or endpoints using a higher-level description language becomes clear here. We're now dealing with just one kind of artifact that is subject to change, enabling us to confidently employ an API-first design process. Nevertheless, as we continually discover, this process involves making and documenting a plethora of decisions.


Fern - Fern

Charge your APIs Volume 10: Crafting API Definitions with TypeSpec

Charge your APIs Volume 11: Taxi Language - Building APIs with Precision and Ease

API-Experience & -Operations: Beratung und Services

share post




More articles in this subject area

Discover exciting further topics and let the codecentric world inspire you.


Gemeinsam bessere Projekte umsetzen.

Wir helfen deinem Unternehmen.

Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.

Hilf uns, noch besser zu werden.

Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.