documentation/dsls/DSL:-AshJsonApi.Resource.cheatmd

Select File:
documentation/dsls/DSL:-AshJsonApi.Resource.cheatmd

# 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](#json_api-routes)
   * get
   * index
   * post
   * patch
   * delete
   * related
   * relationship
   * post_to_relationship
   * patch_relationship
   * delete_from_relationship
 * [primary_key](#json_api-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`* | `String.t` |  | The resource identifier type of this resource in JSON:API |
| `includes` | ``any`` | `[]` | A keyword list of all paths that are includable from this resource |


## json_api.routes
Configure the routes that will be exposed via the JSON:API

### Nested DSLs
 * [get](#json_api-routes-get)
 * [index](#json_api-routes-index)
 * [post](#json_api-routes-post)
 * [patch](#json_api-routes-patch)
 * [delete](#json_api-routes-delete)
 * [related](#json_api-routes-related)
 * [relationship](#json_api-routes-relationship)
 * [post_to_relationship](#json_api-routes-post_to_relationship)
 * [patch_relationship](#json_api-routes-patch_relationship)
 * [delete_from_relationship](#json_api-routes-delete_from_relationship)


### 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`* | `String.t` |  | The base route for the resource, e.g `"/users"` |



## json_api.routes.get
```elixir
get action
```


A GET route to retrieve a single record



### Examples
```
get :read
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `action`* | `atom` |  | The action to call when this route is hit |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `route` | `String.t` | `"/:id"` | The path of the route |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.index
```elixir
index action
```


A GET route to retrieve a list of records



### Examples
```
index :read
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `action`* | `atom` |  | The action to call when this route is hit |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `paginate?` | `boolean` | `true` |  |
| `route` | `String.t` | `"/"` | The path of the route |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.post
```elixir
post action
```


A POST route to create a record



### Examples
```
post :create
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `action`* | `atom` |  | The action to call when this route is hit |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `route` | `String.t` | `"/"` | The path of the route |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |
| `relationship_arguments` | `list(atom \| {:id, atom})` | `[]` | Arguments to be used to edit relationships. See the [relationships guide](/documentation/topics/relationships.md) for more. |
| `upsert?` | `boolean` | `false` | Whether or not to use the `upsert?: true` option when calling `YourApi.create/2`. |
| `upsert_identity` | `atom` | `false` | Which identity to use for the upsert |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.patch
```elixir
patch action
```


A PATCH route to update a record



### Examples
```
patch :update
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `action`* | `atom` |  | The action to call when this route is hit |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `relationship_arguments` | ``any`` | `[]` | Arguments to be used to edit relationships. See the [relationships guide](/documentation/topics/relationships.md) for more. |
| `read_action` | `atom` |  | The read action to use to look the record up before updating |
| `route` | `String.t` | `"/:id"` | The path of the route |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.delete
```elixir
delete action
```


A DELETE route to destroy a record



### Examples
```
delete :destroy
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `action`* | `atom` |  | The action to call when this route is hit |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `read_action` | `atom` |  | The read action to use to look the record up before updating |
| `route` | `String.t` | `"/:id"` | The path of the route |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.related
```elixir
related relationship, action
```


A GET route to read the related resources of a relationship



### Examples
```
related :comments, :read
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `relationship`* | `atom` |  |  |
| `action`* | `atom` |  | The action to call when this route is hit |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `route` | `String.t` |  | The path of the route - Defaults to /:id/[relationship_name] |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.relationship
```elixir
relationship relationship, action
```


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



### Examples
```
relationship :comments, :read
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `relationship`* | `atom` |  |  |
| `action`* | `atom` |  | The action to call when this route is hit |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `route` | `String.t` |  | The path of the route -  Defaults to /:id/relationships/[relationship_name] |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.post_to_relationship
```elixir
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`* | `atom` |  |  |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `route` | `String.t` |  | The path of the route -  Defaults to /:id/relationships/[relationship_name] |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.patch_relationship
```elixir
patch_relationship relationship
```


A PATCH route to update a relationship using resource identifiers



### Examples
```
patch_relationship :comments
```



### Arguments
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `relationship`* | `atom` |  |  |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `route` | `String.t` |  | The path of the route -  Defaults to /:id/relationships/[relationship_name] |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### Introspection

Target: `AshJsonApi.Resource.Route`

## json_api.routes.delete_from_relationship
```elixir
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`* | `atom` |  |  |
### Options
| Name | Type | Default | Docs |
| ---  | ---  | ---     | ---  |
| `route` | `String.t` |  | The path of the route -  Defaults to /:id/relationships/[relationship_name] |
| `default_fields` | `list(atom)` |  | A list of fields to be shown in the attributes of the called 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 |





### 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`* | ``any`` |  | the list of attributes to encode JSON API primary key |
| `delimiter` | `String.t` | `"-"` | The delimiter to concatenate the primary key values. Default to be '-' |