mirror of
https://github.com/ash-project/ash.git
synced 2024-09-21 05:53:06 +12:00
393 lines
7 KiB
Text
393 lines
7 KiB
Text
<!--
|
|
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="resources-resource-resource" href="#resources-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>
|
|
|
|
|
|
|
|
|
|
|
|
|