Api def porting

fern/products/api-definition/fern-definition/api-yml/environments.mdx

@@ -0,0 +1,87 @@
+---
+title: Environments
+description: List environments like production, staging, and development. 
+---
+
+You can specify the environments where your server is deployed. 
+
+## Single URL environments
+
+```yaml title="api.yml"
+name: api
+environments:
+  Production: https://www.yoursite.com
+  Staging:
+    docs: This staging environment is helpful for testing!
+    url: https://www.staging.yoursite.com
+```
+
+## Multiple URLs per environment
+
+You can specify multiple URLs per environment. This is helpful if you have a
+microservice architecture, and you want a single SDK to interact with multiple
+servers.
+
+```yaml title="api.yml"
+environments:
+  Production:
+    urls:
+      Auth: https://auth.yoursite.com
+      Plants: https://plants.yoursite.com
+  Staging:
+    urls:
+      Auth: https://auth.staging.yoursite.com
+      Plants: https://plants.staging.yoursite.com
+```
+
+If you choose to use this feature, you must specify a `url` for each service you define:
+
+```yaml title="auth.yml"
+service:
+  url: Auth
+  base-path: /auth
+  ...
+```
+
+## Default environment
+
+You can also provide a default environment:
+
+```yaml title="api.yml"
+name: api
+environments:
+  Production: https://www.yoursite.com
+  Staging:
+    docs: This staging environment is helpful for testing!
+    url: https://www.staging.yoursite.com
+default-environment: Production
+```
+
+<Note> By providing a default environment, the generated SDK will be setup to hit that URL out-of-the-box. </Note>
+
+## Base path
+If you would like all of your endpoints to be prefixed with a path, use `base-path`. 
+
+In the example below, every endpoint is prefixed with a `/v1`: 
+```yaml title="api.yml"
+name: api
+base-path: /v1
+```
+
+## Audiences
+
+If you have listed environments that you want to filter, you can leverage audiences. 
+
+```yaml title="api.yml"
+audiences:
+  - public
+
+environments:
+  Dev: 
+    url: https://api.dev.buildwithfern.com
+  Prod: 
+    url: https://api.buildwithfern.com
+    audiences:
+      - external
+```
+

fern/products/api-definition/fern-definition/api-yml/errors.mdx

@@ -0,0 +1,54 @@
+---
+title: Errors
+description: Specify error types and schemas
+---
+
+In order to generate SDKs idiomatically, Fern needs to know how to differentiate
+between different errors when parsing an endpoint response.
+
+### Discriminate by status code
+
+You can specify Fern to discriminate by status code. This means on each
+endpoint, every error that's listed must have a different HTTP status code.
+
+<CodeBlock title="api.yml">
+```yaml
+name: api
+error-discrimination:
+  strategy: status-code
+```
+</CodeBlock>
+
+### Discriminate by error name
+
+You can specify Fern to discriminate by error name. If you select this strategy,
+then Fern will assume that every error response has an extra property denoting
+the error name.
+
+If you use Fern to generate server-side code, then this option provides
+the most flexibility. Otherwise, you'll probably want to use the status code
+discrimination strategy.
+
+<CodeBlock title="api.yml">
+```yaml
+name: api
+error-discrimination:
+  strategy: property
+  property-name: errorName
+```
+</CodeBlock>
+
+### Global errors
+
+You can import and list errors that will be thrown by every endpoint.
+
+<CodeBlock title="api.yml">
+```yaml
+imports:
+  commons: commons.yml
+
+errors:
+  - commons.NotFoundError
+  - commons.BadRequestError
+```
+</CodeBlock>

fern/products/api-definition/fern-definition/api-yml/global-configuration.mdx

@@ -0,0 +1,53 @@
+---
+title: Global Configuration
+description: Specify global headers, path parameters or query parameters meant to be included on every request.
+---
+
+The `api.yml` configuration supports global configuration like headers and path parameters. 
+
+## Global headers
+
+You can specify headers that are meant to be included on every request:
+
+<CodeBlock title="api.yml">
+```yaml
+name: api
+headers:
+  X-App-Id: string
+```
+</CodeBlock>
+
+## Global path parameters
+
+You can specify path parameters that are meant to be included on every request:
+
+<CodeBlock title="api.yml">
+```yaml
+name: api
+base-path: /{userId}/{orgId}
+path-parameters:
+  userId: string
+  orgId: string
+```
+</CodeBlock>
+
+### Overriding the base path
+
+If you have certain endpoints that do not live at the configured `base-path`, you can 
+override the `base-path` at the endpoint level. 
+
+```yml imdb.yml {5}
+service: 
+  endpoints: 
+    getMovie: 
+      method: POST
+      base-path: "override/{arg}"
+      path: "movies/{movieId}"
+      path-parameters: 
+        arg: string
+```
+
+## Global query parameters
+
+You cannot yet specify query parameters that are meant to be included on every request.
+If you'd like to see this feature, please upvote [this issue](https://github.com/fern-api/fern/issues/2930).

fern/products/api-definition/fern-definition/api-yml/overview.mdx

@@ -0,0 +1,57 @@
+---
+title: The api.yml configuration file
+description: The api.yml file contains general API configuration when using the Fern Definition format.
+---
+
+A `fern/` folder has a special file called `api.yml`, which includes all the API-wide configuration.
+
+```bash {5}
+fern/
+├─ fern.config.json
+├─ generators.yml
+└─ definition/
+  ├─ api.yml
+  ├─ pet.yml
+  ├─ store.yml
+  └─ user.yml
+```
+
+## API name
+
+This name is used to uniquely identify your API in your organization. If you just have one API, then `api` is a sufficient name.
+
+<CodeBlock title="api.yml">
+```yaml
+name: api
+```
+</CodeBlock>
+
+## API description
+
+You can define a top level API description. This description will come through in the OpenAPI Specification and Postman collection.
+
+<CodeBlock title="api.yml">
+```yaml {2-4}
+name: api
+docs: | 
+  ## Header
+  This API provides access to...
+```
+</CodeBlock>
+
+## API version
+
+You can define your header-based API versioning scheme, such as an `X-API-Version`. The supported versions 
+and default value are specified like so:
+
+<CodeBlock title="api.yml">
+```yaml
+version:
+  header: X-API-Version
+  default: "2.0.0"
+  values:
+    - "1.0.0"
+    - "2.0.0"
+    - "latest"
+```
+</CodeBlock>

fern/products/api-definition/fern-definition/audiences.mdx

@@ -0,0 +1,113 @@
+---
+title: Audiences in Fern Definition 
+subtitle: Use audiences in your Fern Definition to segment your API for different groups of consumers.
+---
+
+Audiences are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an `Audience`. You can use [audiences in your OpenAPI Specification](/learn/api-definition/openapi/audiences), too. 
+
+Common examples of audiences include:
+
+- Internal consumers (e.g., frontend developers who use the API)
+- Beta testers
+- Customers
+
+By default, if no audience is specified, it will be accessible to all consumers. 
+
+## Configuration
+
+The Fern Definition has a first-class concept for marking different endpoints, types, and properties for different audiences. 
+
+To use audiences in your Fern Definition, add them to `api.yml`. 
+
+In the example below, we have created audiences for `internal`, `beta`, and `customer` groups:
+
+```yaml title='api.yml' {2-5}
+name: api 
+audiences: 
+  - internal 
+  - beta 
+  - customers
+```
+
+## Audiences for endpoints
+
+To mark an endpoint for a particular consumer, add an `audience` with the relevant groups. 
+
+In this example, the `sendEmail` endpoint is only available to internal consumers:
+
+```yaml title='user.yml' {6-7}
+service:
+  base-path: /users
+  auth: true
+  endpoints:
+    sendEmail:
+      audiences:
+        - internal
+      path: /send-email
+      ...
+```
+
+## Audiences for types
+
+Types can also be marked for different audiences. 
+
+In this example, the `Email` type is available to internal and beta consumers:
+
+```yaml title='user.yml' {5-7}
+Email: 
+  properties:
+    subject: string
+    body: optional<string>
+  audiences: 
+    - internal
+    - beta
+```
+
+## Audiences for properties
+
+Properties of a type can also be marked for different audiences. 
+
+In this example, the `to` property is available to beta consumers only:
+
+```yaml title='user.yml' {8-9}
+Email: 
+  properties:
+    subject: string
+    body: optional<string>
+    to: 
+      type: string
+      docs: The recipient of the email
+      audiences: 
+        - beta
+```
+
+## Audiences for SDKs
+
+In `generators.yml`, you can apply audience filters so that only certain
+endpoints are passed to the generators. 
+
+The following example configures the SDKs to filter for `customers`:
+
+```yaml title='generators.yml' {3-4}
+groups:
+  external:
+    audiences:
+      - customers
+    generators: 
+    ...
+```
+
+## Audiences with docs 
+
+If generating Fern Docs, update your `docs.yml` configuration to include your audiences. 
+
+The following example shows how to configure your `docs.yml` to publish documentation for the `customers` audience:
+
+<CodeBlock title='docs.yml'>
+```yaml {3-4}
+navigation:
+  - api: API Reference
+    audiences:
+      - customers
+```
+</CodeBlock>