ash/documentation/dsls/DSL:-Ash.Api.cheatmd

<!--
This file was generated by Spark. Do not edit it by hand.
-->
# 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

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Default</th>
      <th colspan=2>Docs</th>
    </tr>
  </thead>
  <tbody>
    <tr>
  <td style="text-align: left">
    <a id="api-description" href="#api-description">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        description
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">String.t</code>
  </td>
  <td style="text-align: left">
    
  </td>
  <td style="text-align: left" colspan=2>
    A description for the api.

  </td>
</tr>

  </tbody>
</table>






## resources
List the resources present in this API

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


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

```




### Options

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Default</th>
      <th colspan=2>Docs</th>
    </tr>
  </thead>
  <tbody>
    <tr>
  <td style="text-align: left">
    <a id="resources-allow" href="#resources-allow">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        allow
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">mfa</code>
  </td>
  <td style="text-align: left">
    
  </td>
  <td style="text-align: left" colspan=2>
    Support a dynamic resource list by providing a callback that checks whether or not the resource should be allowed.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="resources-allow_unregistered?" href="#resources-allow_unregistered?">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        allow_unregistered?
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">boolean</code>
  </td>
  <td style="text-align: left">
    <code class="inline">false</code>
  </td>
  <td style="text-align: left" colspan=2>
    Whether the Api will support only registered entries or not.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="resources-registry" href="#resources-registry">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        registry
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">module</code>
  </td>
  <td style="text-align: left">
    
  </td>
  <td style="text-align: left" colspan=2>
    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.

  </td>
</tr>

  </tbody>
</table>



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


A resource present in the API



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



### Arguments

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Default</th>
      <th colspan=2>Docs</th>
    </tr>
  </thead>
  <tbody>
    <tr>
  <td style="text-align: left">
    <a id="resource-resource" href="#resource-resource">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        resource
      </span>
    </a>
      <sup style="color: red">*</sup>

  </td>
  <td style="text-align: left">
    <code class="inline">module</code>
  </td>
  <td style="text-align: left">
    
  </td>
  <td style="text-align: left" colspan=2>
    
  </td>
</tr>

  </tbody>
</table>






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

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Default</th>
      <th colspan=2>Docs</th>
    </tr>
  </thead>
  <tbody>
    <tr>
  <td style="text-align: left">
    <a id="execution-timeout" href="#execution-timeout">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        timeout
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">timeout</code>
  </td>
  <td style="text-align: left">
    <code class="inline">30000</code>
  </td>
  <td style="text-align: left" colspan=2>
    The default timeout to use for requests using this API. See the [timeouts guide](/documentation/topics/timeouts.md) for more.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="execution-trace_name" href="#execution-trace_name">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        trace_name
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">String.t</code>
  </td>
  <td style="text-align: left">
    
  </td>
  <td style="text-align: left" colspan=2>
    The name to use in traces. Defaults to the last part of the module. See the [monitoring guide](/documentation/topics/monitoring.md) for more

  </td>
</tr>

  </tbody>
</table>






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

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Default</th>
      <th colspan=2>Docs</th>
    </tr>
  </thead>
  <tbody>
    <tr>
  <td style="text-align: left">
    <a id="authorization-require_actor?" href="#authorization-require_actor?">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        require_actor?
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">boolean</code>
  </td>
  <td style="text-align: left">
    <code class="inline">false</code>
  </td>
  <td style="text-align: left" colspan=2>
    Requires that an actor has been supplied.
  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="authorization-authorize" href="#authorization-authorize">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        authorize
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">:always | :by_default | :when_requested</code>
  </td>
  <td style="text-align: left">
    <code class="inline">:when_requested</code>
  </td>
  <td style="text-align: left" colspan=2>
    When to run authorization for a given request.

  </td>
</tr>

  </tbody>
</table>