# 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": ""
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://domainmappingsystem.gitbook.io/domainmappingsystem-docs/features/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.