In Fern, you organize related endpoints into a Service. This grouping improves clarity and makes the generated SDKs more idiomatic.
Each service defines:
- A base-path: A common prefix for all the endpoints' HTTP paths
- Whether the service requires authentication
An endpoint includes:
- A URL path (Optionally including path parameters)
- An HTTP Method
- Request information (Optional)
- Request body
- Successful (200) response information (Optional)
- Error (non-200) responses that this endpoint might return (Optional)
Each endpoint has a URL path.
The full path for the endpoint is the concatenation of:
- The environment URL
- The service
- The endpoint
Supply path parameters for your endpoints to create dynamic URLs.
Services can also have path-parameters:
Each endpoint can specify query parameters:
allow-multiple to specify that a query parameter is allowed
multiple times in the URL, as in
?filter=jane&filter=smith. This will alter
the generated SDKs so that consumers can provide multiple values for the query
Each endpoint can override the auth behavior specified in the service.
Each endpoint can specify request headers:
Services can also specify request headers. These headers will cascade to the service's endpoints.
Endpoints can specify a request body type.
Inlining a request body
If the request body is an object, you can inline the type declaration. This makes the generated SDKs a bit more idiomatic.
Multipart form uploads
If the request involves uploading a file, use the
in your request body.
Endpoints can specify a
response, which is the type of the body that will be
returned on a successful (200) call.
Endpoints can specify error responses, which detail the non-200 responses that the endpoint might return.
You can learn more about how to define errors on the Errors page.
When you declare an example, you can also specify some examples of how that endpoint might be used. These are used by the compiler to enhance the generated outputs. Examples will show up as comments in your SDKs, API documentation, and Postman collection.
You may add examples for endpoints, types, and errors.
If you're adding an example to an endpoint and the type already has an example, you can reference it using
Examples contain all the information about the endpoint call, including the request body, path paramters, query parameters, headers, and response body.
You can also specify examples of failed endpoints calls. Add the
property to a response example to designate which failure you're demonstrating.
If the error has a body, then you must include the body in the example.
Referencing examples from types
To avoid duplication, you can reference examples from types using