REST API

Using the WordPress REST API, you can easily add or update mapped domains in Domain Mapping System.

Domain Mapping System takes advantage of the WordPress REST API to allow adding and deleting of domain mappings.

When Domain Mapping System is installed, by default, the REST API URL is available on your site at this kind of URL:

https://your-domain.com/api/dms/v1

Be sure to replace your-domain with your primary domain name configured on your WordPress site. This can be founder under the Settings > General tab in the WP-Admin Menu.

The API requires a Token Request for valid authentication. Then, you can add/update mappings as desired.

1. Token Request

Authentication to the REST API is facilitated via JSON Web Token (JWT).

First, you must request a token by logging in using the below endpoint and valid WordPress admin credentials.

When requesting the token by logging in, the new JWT will be generated for you and passed in response to the request.

The token will later be required to authorize all calls to the API using the Bearer Token authentication method.

The token is tied to the admin user account. If the admin user account is ever deleted, the token will no longer work.

POST /wp-json/dms/v1/token

--body { "user_name": "[e-mail]", "password": "******" }

Request Body

Name	Type	Description
user_name*	string	WordPress Admin account username or email
password*	string	WordPress Admin account password

200: OK Success

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiMSJ9.CLFgmmXt0xVKBMhkpy67ULD_d79-XFI0JtuiOMqAYMw"
} 

400: Bad Request Invalid content type

{
    "code": "invalid_content_type",
    "message": "Invalid content type. Please check our documentation https://docs.domainmappingsystem.com/features/rest-api",
    "data": 
    {
         "status": 400
    }
}

400: Bad Request Invalid JSON body passed

{
    "code": "rest_invalid_json",
    "message": "Invalid JSON body passed",
    "data": 
    {
         "status": 400
    }
}

400: Bad Request Empty username field

{
    "code": "empty_username_field",
    "message": "Empty username field",
    "data": 
    {
         "status": 400
    }
}

400: Bad Request Empty password field

{
    "code": "empty_password_field",
    "message": "Empty password field",
    "data": 
    {
         "status": 400
    }
}

400: Bad Request Unable to get token. Please connect to site owner and read our documentation

{
    "code": "unable_to_get_token",
    "message": "Unable to get token. Please contact the site administrator owner and review our documentation",
    "data": 
    {
         "status": 400
    }
}

400: Bad Request Technical error. Please reach out to support and read our documentation

{
    "code": "technical_error",
    "message": "Technical error. Please contact support and review our documentation",
    "data": 
    {
         "status": 400
    }
}

2. Add/Update Mapping

This request does not support bulk changes. You can add/update only one object per request. If the website is using the free version of the plugin, then you will not be able to add multiple values per mapping or set up a primary value. This means you cannot set up Microsites (or a Microsite homepage), which are paid features.

Free Version Request

POST /wp-json/dms/v1/mappings

--header Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiMSJ9.CLFgmmXt0xVKBMhkpy67ULD_d79-XFI0JtuiOMqAYMw

--body { "host": "example.com", "value": 6 }

Headers

Name	Type	Description
Authorization: Bearer*	string	Token

Request Body

Name	Type	Description
host*	string	Desired mapped domain
value*	integer or string	Either post ID or category slug

200: OK Successfully saved

{
    "message": "Successfully saved"
}

400: Bad Request Invalid content type

{
    "code": "invalid_content_type",
    "message": "Invalid content type",
    "data": 
    {
        "status": 400
    }
}

400: Bad Request Host and value are required

{
    "code": "host_and_value_are_required",
    "message": "Host and value are required",
    "data": 
    {
        "status": 400
    }
}

400: Bad Request Invalid host specified

{
    "code": "invalid_host_specified",
    "message": "Invalid host specified",
    "data": 
    {
        "status": 400
    }
}

400: Bad Request Invalid values exist

{
    "code": "invalid_values_exist",
    "message": "Invalid values exist",
    "data": 
    {
        "status": 400
        }
}

400: Bad Request Unable to map primary domain. Please check our documentation

{
    "code": "unable_to_map_primary_domain",
    "message": "Unable to map primary domain. Please check our documentation",
    "data": 
    {
        "status": 400
    }
}

400: Bad Request Duplicate entries detected with the same root domain and subdirectory

{
    "code": "duplicate_entries_detected_with_the_same_root_domain_and_subdirectory",
    "message": "Duplicate entries detected with the same root domain and subdirectory",
    "data": 
    {
        "status": 400
    }
}

Paid Version Request

POST /wp-json/dms/v1/mappings

--header Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiMSJ9.CLFgmmXt0xVKBMhkpy67ULD_d79-XFI0JtuiOMqAYMw

--body { "host": "example.com", "path": "some_path", "primary": 0, "value": 6 }

Headers

Name	Type	Description
Authorization: Bearer*	string	Token

Request Body

Name	Type	Description
host*	string	Desired mapped domain
path*	string	Valid URL path for subdirectory mapping
primary*	boolean	0 => Set as primary value and make this published resource the microsite homepage 1 => Not as not primary value
value*	integer or string	Either post ID or category slug

200: OK Successfully saved

{
    "message": "Successfully saved"
}

400: Bad Request Invalid content type

{
    "code": "invalid_content_type",
    "message": "Invalid content type",
    "data": 
    {
        "status": 400
    }
}

400: Bad Request Host and value are required

{
    "code": "host_and_value_are_required",
    "message": "Host and value are required",
    "data": 
    {
        "status": 400
    }
}

400: Bad Request Invalid host specified

{
    // Response
}

400: Bad Request Invalid paths specified

{
    // Response
}

400: Bad Request Invalid values exist

{
    "code": "invalid_values_exist",
    "message": "Invalid values exist",
    "data": 
    {
        "status": 400
    }
}

400: Bad Request Unable to map primary domain. Please check our documentation

{
    "code": "unable_to_map_primary_domain",
    "message": "Unable to map primary domain. Please check our documentation",
    "data": 
    {
        "status": 400
    }
}

400: Bad Request Duplicate entries detected with the same root domain and subdirectory

{
    "code": "duplicate_entries_detected_with_the_same_root_domain_and_subdirectory",
    "message": "Duplicate entries detected with the same root domain and subdirectory",
    "data": 
    {
        "status": 400
    }
}