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.
1. 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=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json
2
3service:
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: hank.henderson@email.com
26 phoneNumber: 555-555-5555
27 # Error response
28 - path-parameters:
29 id: tt1234
30 response:
31 error: CustomerDoesNotExistError
32 body: tt1234
33
34types:
35 CustomerId:
36 type: string
37 docs: The unique identifier for a customer
38
39 Customer:
40 properties:
41 id: CustomerId
42 firstName: string
43 lastName: string
44 email: string
45 phoneNumber: string
46
47errors:
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
2groups:
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 5┌─ 6│ ✓ fernapi/fern-openapi 7│ ✓ fernapi/fern-postman 8│ ✓ fernapi/fern-java-spring 9└─
Conclusion
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.
References
Charge your APIs Volume 10: Crafting API Definitions with TypeSpec
Charge your APIs Volume 11: Taxi Language - Building APIs with Precision and Ease
Was this post helpful?
More articles
fromDaniel Kocot
11.12.2024 Your job at codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
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.
Blog author
Daniel Kocot
Senior Solution Architect / Head of API Consulting
Do you still have questions? Just send me a message.
Do you still have questions? Just send me a message.