## Categories

This endpoint allows you to `list`, `create`, `retrieve`, `update` and `delete` your categories.

The endpoint responses are formatted according to the [JSON:API specification](https://jsonapi.org).

### The category object

#### Attributes

| Key                  | Type      | Description                                                  |
| -------------------- | --------- | ------------------------------------------------------------ |
| `name`           | `string`  | **Required**. The category's name         |
| `permalink_slug`           | `string`  | The category's permalink slug.         |
| `parent_id`           | `integer`  | The Unique identifier of the parent category, if any.         |
| `locations`           | `array`  | The category's locations, if any.         |
| `priority`           | `integer`  | The category's priority.         |
| `status`           | `boolean`  | Has the value `true` if the category is enabled or the value `false` if the category is disabled.         |
| `description`           | `string`  | An arbitrary string attached to the category.         |
| `thumb`           | `string`  | The URL where the category's thumbnail can be accessed.         |

#### Category object example

```json
{
  "name": "Appetizer",
  "permalink_slug": "appetizer",
  "parent_id": null,
  "locations": [],
  "priority": null,
  "status": true,
  "description": "Sed consequat, sapien in scelerisque egestas",
  "thumb": null
}
```

### List categories

Returns a list of categories you’ve previously created.

Required abilities: `categories:read`

```
GET /api/categories
```

#### Parameters

| Key                  | Type      | Description          |
| -------------------- | --------- | ------------------------- |
| `page`           | `integer`  | The page number.         |
| `pageLimit`           | `integer`  | The number of items per page.         |
| `include`           | `string`  | What relations to include in the response. Options are `media`, `menus`, `locations`. To include multiple seperate by comma (e.g. ?include=media,menus) |

#### Response

```html
Status: 200 OK
```

```json
{
  "data": [
    {
      "type": "categories",
      "id": "1",
      "attributes": {
        "name": "Appetizer",
        "permalink_slug": "appetizer",
        "parent_id": null,
        "priority": null,
        "status": true,
        "description": "Sed consequat, sapien in scelerisque egestas",
        "thumb": null,
        "media": [...],
        "menus": [...],
        "locations": [...]
      },
      "relationships": {
        "menus": {
          "data": [...]
        },
        "locations": {
          "data": [...]
        }
      }
    }
  ],
  "included": [
    ...
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 1
    }
  },
  "links": {
    "self": "https://your.url/api/categories?page=1",
    "first": "https://your.url/api/categories?page=1",
    "last": "https://your.url/api/categories?page=1"
  }
}
```

### Create a category

Creates a new category.

Required abilities: `categories:write`

```
POST /api/categories
```

#### Parameters

| Key                  | Type      | Description                                                  |
| -------------------- | --------- | ------------------------------------------------------------ |
| `name`           | `string`  | **Required**. The category's name         |
| `permalink_slug`           | `string`  | The category's permalink slug.         |
| `parent_id`           | `integer`  | The Unique identifier of the parent category, if any.         |
| `locations`           | `array`  | The category's locations, if any.         |
| `priority`           | `integer`  | The category's priority.         |
| `status`           | `boolean`  | Has the value `true` if the category is enabled or the value `false` if the category is disabled.         |
| `description`           | `string`  | An arbitrary string attached to the category.         |
| `thumb`           | `string`  | The URL where the category's thumbnail can be accessed.         |

#### Payload example

```json
{
  "name": "Appetizer",
  "status": true
}
```

#### Response

```html
Status: 201 Created
```

```json
{
  "data": [
    {
      "type": "categories",
      "id": "1",
      "attributes": {
        "name": "Appetizer",
        "permalink_slug": "appetizer",
        "parent_id": null,
        "priority": null,
        "status": true,
        "description": "Sed consequat, sapien in scelerisque egestas",
        "thumb": null,
      }
    }
  ]
}
```

### Retrieve a category

Retrieves a category.

Required abilities: `categories:read`

```
GET /api/categories/:category_id
```

#### Parameters

| Key                  | Type      | Description          |
| -------------------- | --------- | ------------------------- |
| `include`           | `string`  | What relations to include in the response. Options are `media`, `menus`, `locations`. To include multiple seperate by comma (e.g. ?include=media,menus) |

#### Response

```html
Status: 200 OK
```

```json
{
  "data": [
    {
      "type": "categories",
      "id": "1",
      "attributes": {
        "name": "Appetizer",
        "permalink_slug": "appetizer",
        "parent_id": null,
        "priority": null,
        "status": true,
        "description": "Sed consequat, sapien in scelerisque egestas",
        "thumb": null,
        "media": [...],
        "menus": [...],
        "locations": [...]
      },
      "relationships": {
        "menus": {
          "data": [...]
        },
        "locations": {
          "data": [...]
        }
      }
    }
  ],
  "included": [
	...
  ]
}
```

### Update a category

Updates a category.

Required abilities: `categories:write`

```
PATCH /api/categories/:category_id
```

#### Parameters

| Key                  | Type      | Description                                                  |
| -------------------- | --------- | ------------------------------------------------------------ |
| `name`           | `string`  | **Required**. The category's name         |
| `permalink_slug`           | `string`  | The category's permalink slug.         |
| `parent_id`           | `integer`  | The Unique identifier of the parent category, if any.         |
| `locations`           | `array`  | The category's locations, if any.         |
| `priority`           | `integer`  | The category's priority.         |
| `status`           | `boolean`  | Has the value `true` if the category is enabled or the value `false` if the category is disabled.         |
| `description`           | `string`  | An arbitrary string attached to the category.         |
| `thumb`           | `string`  | The URL where the category's thumbnail can be accessed.         |

#### Payload example

```json
{
  "description": "Vivamus interdum erat ac aliquam porttitor. ",
  "parent_id": 2
}
```

#### Response

```html
Status: 200 OK
```

```json
{
  "data": [
    {
      "type": "categories",
      "id": "1",
      "attributes": {
        "name": "Appetizer",
        "permalink_slug": "appetizer",
        "parent_id": null,
        "priority": null,
        "status": true,
        "description": "Sed consequat, sapien in scelerisque egestas",
        "thumb": null,
      }
    }
  ]
}
```

### Delete a category

Permanently deletes a category. It cannot be undone.

Required abilities: `categories:write`

```
DELETE /api/categories/:category_id
```

#### Parameters

No parameters.

#### Response

Returns an object with a deleted parameter on success. If the category ID does not exist, this call returns an error.

```html
Status: 200 OK
```

```json
{
  "id": 1,
  "object": "category",
  "deleted": true
}
```