# DSL: Ash.Api.Dsl

Apis are the entrypoints for working with your resources.

Apis may optionally include a list of resources, in which case they can be
used as an `Ash.Registry` in various places. This is for backwards compatibility,
but if at all possible you should define an `Ash.Registry` if you are using an extension
that requires a list of resources. For example, most extensions look for two application
environment variables called `:ash_apis` and `:ash_registries` to find any potential registries


## api
General Api configuration



### Examples
```
api do
  description """
  Resources related to the flux capacitor.
  """
end

```




### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `description` | `String.t` |  | A description for the api. |






## resources
List the resources present in this API

### Nested DSLs
 * [resource](#resources-resource)


### Examples
```
resources do
  resource MyApp.Tweet
  resource MyApp.Comment
end

```




### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `allow` | `mfa` |  | Support a dynamic resource list by providing a callback that checks whether or not the resource should be allowed. |
| `allow_unregistered?` | `boolean` | false | Whether the Api will support only registered entries or not. |
| `registry` | `module` |  | Configure a registry that contains the resources. This option is generally not necessary anymore, and remains for backwards compatibility. Instead, configure resources in this block directly. |



## resources.resource
```elixir
resource resource
```


A resource present in the API



### Examples
```
resource Foo
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `resource`* | `module` |  |  |






### Introspection

Target: `Ash.Api.Dsl.ResourceReference`




## execution
Options for how requests are executed using this Api



### Examples
```
execution do
  timeout :timer.seconds(30)
end

```




### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `timeout` | `timeout` | 30000 | The default timeout to use for requests using this API. See the [timeouts guide](/documentation/topics/timeouts.md) for more. |
| `trace_name` | `String.t` |  | The name to use in traces. Defaults to the last part of the module. See the [monitoring guide](/documentation/topics/monitoring.md) for more |






## authorization
Options for how requests are authorized using this Api. See the [security guide](/documentation/topics/security.md) for more.




### Examples
```
authorization do
  authorize :by_default
end

```




### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `require_actor?` | `boolean` | false | Requires that an actor has been supplied. |
| `authorize` | `:always \| :by_default \| :when_requested` | :when_requested | When to run authorization for a given request. |