Skip to content

Latest commit

 

History

History
645 lines (410 loc) · 31.8 KB

DSL:-AshJsonApi.Resource.md

File metadata and controls

645 lines (410 loc) · 31.8 KB
Raw

DSL: AshJsonApi.Resource

The entrypoint for adding JSON:API behavior to a resource"

json_api

Configure the resource's behavior in the JSON:API

Nested DSLs

  • routes
    • get
    • index
    • post
    • patch
    • delete
    • related
    • relationship
    • post_to_relationship
    • patch_relationship
    • delete_from_relationship
    • route
  • primary_key

Examples

json_api do
  type "post"
  includes [
    friends: [
      :comments
    ],
    comments: []
  ]

  routes do
    base "/posts"

    get :read
    get :me, route: "/me"
    index :read
    post :confirm_name, route: "/confirm_name"
    patch :update
    related :comments, :read
    relationship :comments, :read
    post_to_relationship :comments
    patch_relationship :comments
    delete_from_relationship :comments
  end
end

Options

Name Type Default Docs
type{: #json_api-type } String.t The resource identifier type of this resource in JSON:API
includes{: #json_api-includes } any [] A keyword list of all paths that are includable from this resource
include_nil_values?{: #json_api-include_nil_values? } any Whether or not to include properties for values that are nil in the JSON output
default_fields{: #json_api-default_fields } list(atom) The fields to include in the object if the fields query parameter does not specify. Defaults to all public
derive_sort?{: #json_api-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

json_api.routes

Configure the routes that will be exposed via the JSON:API

Nested DSLs

Examples

routes do
  base "/posts"

  get :read
  get :me, route: "/me"
  index :read
  post :confirm_name, route: "/confirm_name"
  patch :update
  related :comments, :read
  relationship :comments, :read
  post_to_relationship :comments
  patch_relationship :comments
  delete_from_relationship :comments
end

Options

Name Type Default Docs
base{: #json_api-routes-base } String.t A base route for the resource, e.g "/users"

json_api.routes.get

get action

A GET route to retrieve a single record

Examples

get :read

Arguments

Name Type Default Docs
action{: #json_api-routes-get-action .spark-required} atom The action to call when this route is hit

Options

Name Type Default Docs
route{: #json_api-routes-get-route } String.t "/:id" The path of the route
default_fields{: #json_api-routes-get-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-get-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-get-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-get-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
name{: #json_api-routes-get-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-get-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-get-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.index

index action

A GET route to retrieve a list of records

Examples

index :read

Arguments

Name Type Default Docs
action{: #json_api-routes-index-action .spark-required} atom The action to call when this route is hit

Options

Name Type Default Docs
paginate?{: #json_api-routes-index-paginate? } boolean true
route{: #json_api-routes-index-route } String.t "/" The path of the route
default_fields{: #json_api-routes-index-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-index-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-index-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-index-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
name{: #json_api-routes-index-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-index-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-index-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.post

post action

A POST route to create a record

Examples

post :create

Arguments

Name Type Default Docs
action{: #json_api-routes-post-action .spark-required} atom The action to call when this route is hit

Options

Name Type Default Docs
route{: #json_api-routes-post-route } String.t "/" The path of the route
default_fields{: #json_api-routes-post-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-post-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-post-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-post-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-post-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-post-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-post-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-post-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource
relationship_arguments{: #json_api-routes-post-relationship_arguments } list(atom | {:id, atom}) [] Arguments to be used to edit relationships. See the relationships guide for more.
upsert?{: #json_api-routes-post-upsert? } boolean false Whether or not to use the upsert?: true option when calling Ash.create/2.
upsert_identity{: #json_api-routes-post-upsert_identity } atom false Which identity to use for the upsert

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.patch

patch action

A PATCH route to update a record

Examples

patch :update

Arguments

Name Type Default Docs
action{: #json_api-routes-patch-action .spark-required} atom The action to call when this route is hit

Options

Name Type Default Docs
relationship_arguments{: #json_api-routes-patch-relationship_arguments } any [] Arguments to be used to edit relationships. See the relationships guide for more.
read_action{: #json_api-routes-patch-read_action } atom The read action to use to look the record up before updating
route{: #json_api-routes-patch-route } String.t "/:id" The path of the route
default_fields{: #json_api-routes-patch-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-patch-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-patch-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-patch-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-patch-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-patch-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-patch-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-patch-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.delete

delete action

A DELETE route to destroy a record

Examples

delete :destroy

Arguments

Name Type Default Docs
action{: #json_api-routes-delete-action .spark-required} atom The action to call when this route is hit

Options

Name Type Default Docs
read_action{: #json_api-routes-delete-read_action } atom The read action to use to look the record up before updating
route{: #json_api-routes-delete-route } String.t "/:id" The path of the route
default_fields{: #json_api-routes-delete-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-delete-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-delete-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-delete-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-delete-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-delete-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-delete-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-delete-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.related

related relationship, action

A GET route to read the related resources of a relationship

Examples

related :comments, :read

Arguments

Name Type Default Docs
relationship{: #json_api-routes-related-relationship .spark-required} atom
action{: #json_api-routes-related-action .spark-required} atom The action to call when this route is hit

Options

Name Type Default Docs
route{: #json_api-routes-related-route } String.t The path of the route - Defaults to /:id/[relationship_name]
default_fields{: #json_api-routes-related-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-related-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-related-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-related-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-related-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-related-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-related-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-related-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.relationship

relationship relationship, action

A READ route to read the relationship, returns resource identifiers.

Examples

relationship :comments, :read

Arguments

Name Type Default Docs
relationship{: #json_api-routes-relationship-relationship .spark-required} atom
action{: #json_api-routes-relationship-action .spark-required} atom The action to call when this route is hit

Options

Name Type Default Docs
route{: #json_api-routes-relationship-route } String.t The path of the route - Defaults to /:id/relationships/[relationship_name]
default_fields{: #json_api-routes-relationship-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-relationship-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-relationship-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-relationship-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-relationship-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-relationship-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-relationship-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-relationship-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.post_to_relationship

post_to_relationship relationship

A POST route to create related entities using resource identifiers

Examples

post_to_relationship :comments

Arguments

Name Type Default Docs
relationship{: #json_api-routes-post_to_relationship-relationship .spark-required} atom

Options

Name Type Default Docs
route{: #json_api-routes-post_to_relationship-route } String.t The path of the route - Defaults to /:id/relationships/[relationship_name]
default_fields{: #json_api-routes-post_to_relationship-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-post_to_relationship-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-post_to_relationship-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-post_to_relationship-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-post_to_relationship-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-post_to_relationship-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-post_to_relationship-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-post_to_relationship-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.patch_relationship

patch_relationship relationship

A PATCH route to update a relationship using resource identifiers

Examples

patch_relationship :comments

Arguments

Name Type Default Docs
relationship{: #json_api-routes-patch_relationship-relationship .spark-required} atom

Options

Name Type Default Docs
route{: #json_api-routes-patch_relationship-route } String.t The path of the route - Defaults to /:id/relationships/[relationship_name]
default_fields{: #json_api-routes-patch_relationship-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-patch_relationship-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-patch_relationship-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-patch_relationship-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-patch_relationship-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-patch_relationship-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-patch_relationship-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-patch_relationship-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.delete_from_relationship

delete_from_relationship relationship

A DELETE route to remove related entities using resource identifiers

Examples

delete_from_relationship :comments

Arguments

Name Type Default Docs
relationship{: #json_api-routes-delete_from_relationship-relationship .spark-required} atom

Options

Name Type Default Docs
route{: #json_api-routes-delete_from_relationship-route } String.t The path of the route - Defaults to /:id/relationships/[relationship_name]
default_fields{: #json_api-routes-delete_from_relationship-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-delete_from_relationship-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-delete_from_relationship-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-delete_from_relationship-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-delete_from_relationship-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-delete_from_relationship-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-delete_from_relationship-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-delete_from_relationship-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.routes.route

route method, route, action

A route for a generic action.

Examples

route :get, "say_hi/:name", :say_hello"

Arguments

Name Type Default Docs
method{: #json_api-routes-route-method .spark-required} atom The HTTP method for the route, e.g :get, or :post
route{: #json_api-routes-route-route .spark-required} String.t The path of the route
action{: #json_api-routes-route-action .spark-required} atom The action to call when this route is hit

Options

Name Type Default Docs
wrap_in_result?{: #json_api-routes-route-wrap_in_result? } boolean false Whether or not the action result should be wrapped in {result: <result>}
default_fields{: #json_api-routes-route-default_fields } list(atom) A list of fields to be shown in the attributes of the called route
primary?{: #json_api-routes-route-primary? } boolean false Whether or not this is the route that should be linked to by default when rendering links to this type of route
metadata{: #json_api-routes-route-metadata } (any, any, any -> any) A function to generate arbitrary top-level metadata for the JSON:API response
modify_conn{: #json_api-routes-route-modify_conn } (any, any, any, any -> any) A function to modify the conn before responding. Used for things like setting headers based on the response. Takes conn, subject, result, request
query_params{: #json_api-routes-route-query_params } list(atom) [] A list of action inputs to accept as query parameters.
name{: #json_api-routes-route-name } String.t A globally unique name for this route, to be used when generating docs and open api specifications
derive_sort?{: #json_api-routes-route-derive_sort? } boolean true Whether or not to derive a sort parameter based on the sortable fields of the resource
derive_filter?{: #json_api-routes-route-derive_filter? } boolean true Whether or not to derive a filter parameter based on the sortable fields of the resource

Introspection

Target: AshJsonApi.Resource.Route

json_api.primary_key

Encode the id of the JSON API response from selected attributes of a resource

Examples

primary_key do
  keys [:first_name, :last_name]
  delimiter "~"
end

Options

Name Type Default Docs
keys{: #json_api-primary_key-keys .spark-required} atom | list(atom) the list of attributes to encode JSON API primary key
delimiter{: #json_api-primary_key-delimiter } String.t "-" The delimiter to concatenate the primary key values. Default to be '-'
<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>