# REST API

This documentation covers all available endpoints for managing domains and their associated mapping values. 

{% hint style="success" %}
You can also view this documentation in [Postman](https://documenter.getpostman.com/view/2028742/2sAY4siPVS), but be sure to review the important notes and authentication flow details below. 
{% endhint %}

{% hint style="warning" %}
Important notes:

* All requests must be authenticated using the provided credentials.
* Ensure that proper permissions are set for users accessing the API.
* For testing, it is recommended to use Postman or similar tools to make authenticated requests.
  {% endhint %}

### About Authentication Flow

The REST API follows a multi-layered approach for authentication:

1. **Check if the User is Logged In**:
   * If a user is logged in, the system first verifies a **nonce**. For the nonce to be valid, the user must have the **admin role**.
2. **If the User is Not Logged In**:
   * The system requires **application password authentication**. It checks if a user with the provided username and password exists and has the **admin role**. If so, the user is authenticated.

This approach provides flexibility:

* **Internal integrators** can authenticate using either a **nonce** or **application passwords**.
* **External integrators** are restricted to using **application passwords**.

### Rest API Documentation

### Base URL

```
{{base_url}}/wp-json/dms/v1/
```

Replace `{{base_url}}` with your WordPress installation URL.

***

### Authentication

The DMS API uses basic authentication. Include the following credentials in each request:

* **Username**: `TestUser`
* **Password**: `DaEO Wj4v hl3Y 4ZZy 5Lxu E4GF`

Ensure you keep these credentials secure and change them for production environments.

***

### Endpoints

#### 1. Mappings

**GET All Mappings**

Fetch all mappings.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mappings/`
* **Method**: `GET`
* **Query Parameters**:
  * `include[]=mapping_values` (optional): Includes mapping values.
  * `include[]=mapping_metas` (optional): Includes mapping metadata.

**GET Single Mapping**

Fetch details for a specific mapping by ID.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mappings/{id}`
* **Method**: `GET`
* **Path Parameter**:
  * `id` (integer): ID of the mapping.

**POST Create Mapping**

Create a new mapping.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mappings/`
* **Method**: `POST`
* **Body**:

  ```json
  {
    "host": "dev5.dms.local",
    "path": "path",
    "attachment_id": "",
    "custom_html": "<meta content='metaContent' name='metaName'>"
  }
  ```

**PUT Update Mapping**

Update an existing mapping.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mappings/{id}`
* **Method**: `PUT`
* **Body**:

  ```json
  {
    "host": "dev1.dms.local",
    "path": "path1/path2/path3",
    "attachment_id": 123456,
    "custom_html": "<script>"
  }
  ```

**DELETE Mapping**

Delete a mapping.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mappings/{id}`
* **Method**: `DELETE`

***

#### 2. Mapping Values

**GET All Mapping Values**

Fetch all values for a specific mapping.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mappings/{id}/values`
* **Method**: `GET`
* **Path Parameter**:
  * `id` (integer): ID of the mapping.
* **Query Parameters**:
  * `include[]=object` (optional): Includes the associated object.
  * `include[]=mapped_link` (optional): Includes the mapped link.

**POST Create Mapping Value**

Create a new mapping value.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mappings/{id}/values/`
* **Method**: `POST`
* **Body**:

  ```json
  {
    "object_type": "post",
    "object_id": 55,
    "primary": 1,
    "mapping_id": 26
  }
  ```

**PUT Update Mapping Value**

Update an existing mapping value.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mapping_values/{value_id}`
* **Method**: `PUT`
* **Body**:

  ```json
  {
    "mapping_id": 2,
    "object_id": null,
    "object_type": "cpt",
    "primary": 0
  }
  ```

**DELETE Mapping Value**

Delete a mapping value.

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mapping_values/{value_id}`
* **Method**: `DELETE`

***

#### 3. Batch Operations

**POST Batch Operation for Mappings**

Perform batch operations on mappings (create, update, delete).

* **Endpoint**: `{{base_url}}/wp-json/dms/v1/mappings/batch`
* **Method**: `POST`
* **Body**:

  ```json
  [
    {
      "method": "create",
      "data": [
        {
          "host": "dev8.dms.local",
          "path": "",
          "attachment_id": 123456,
          "custom_html": ""
        }
      ]
    },
    {
      "method": "update",
      "data": [
        {
          "id": 30,
          "host": "dev2.dms.local",
          "path": "updated_path",
          "attachment_id": 123456
        }
      ]
    },
    {
      "method": "delete",
      "data": [
        {
          "id": 27
        }
      ]
    }
  ]
  ```

***

### Response Format

Responses are returned in JSON format. A typical response looks like this:

```json
{
    "success": true,
    "data": {
        "mapping": {
            "id": 29,
            "host": "dev5.dms.local",
            "path": "path",
            "attachment_id": 0,
            "custom_html": ""
        }
    }
}
```