# 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.
|