View Source Ash.Api.Dsl (ash v1.52.0-rc.21)
A small DSL for declaring APIs
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
dsl-documentation
DSL Documentation
index
Index
docs
Docs
resources
resources
List the resources present in this API
Examples:
resources do
registry MyApp.Registry
end
:allow
- Support a dynamic resource list by providing a callback that checks whether or not the resource should be allowed.:allow_unregistered?
- By default, an api will only work with resources that are explicitly included in the provided registry. In order to separate your application into multiple domains, you may wish to "mix and match" your resources across contexts. Specifying this option allows you to refer to resources in different apis in your resources, and allows providing any resource to api actions (to facilitate that requirement).
Be sure to remove the Ash.Registry.ResourceValidations extension from your registry as well. The default value isfalse
.:registry
- Allows declaring that only the modules in a certain registry should be allowed to work with this Api.
This option is ignored if any explicit resources are included in the api, so everything is either in the registry or in the api. See the docs onAsh.Registry
for what the registry is used for.
To optimize for compile times, you can place the connection from the api to the registry in application configuration.
To accomplish this:
- Configure an
otp_app
when using your api, e.guse Ash.Api, otp_app: :my_app
- Add application config to set up the connection
config :my_app, MyApp.Api, resources: [ registry: MyApp.Api.Registry ]
execution
execution
Options for how requests are executed using this Api
Examples:
execution do
timeout :timer.seconds(30)
end
:timeout
- The default timeout to use for requests using this API. The default value is30000
.
authorization
authorization
Options for how requests are authorized using this Api
Examples:
execution do
always_authorize? true
require_actor? true
end
:require_actor?
- Requires that an actor has been supplied. Important:nil
is still a valid actor, so this won't prevent providingactor: nil
. This is effectively the same as settingalways_authorize?
totrue
, because providing an actor causes authorization to happen. The default value isfalse
.:always_authorize?
- Forcesauthorize?: true
on all requests to the Api, but allows for an actor not to be set, authorizing withnil
(which is a valid actor, i.e for unauthenticated actions)
To require that an actor is always set, userequire_actor?
instead (or in addition, will be the same effect). The default value isfalse
.