# Domain aliases

Note: this API is in beta currently and is subject to change in the future.

## Domain aliases

The Domain aliases resource allows creation of alternate URLs for Site objects that can be hosted under a different domain and/or directory. These URLs render a copy of the Site, but can modify certain fields to change their properties.

The most common use of Domain aliases is to create alternate URLs for different languages or language/regions.

## Domain alias object

### Domain alias model

A domain alias contains the following fields

| Attribute          | Type      | Description                                                                                                                                  |
| ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| id                 | integer   | unique id of the domain alias                                                                                                                |
| site\_id           | integer   | Reference id to the Site this domain alias is connected to                                                                                   |
| user\_id           | integer   | Reference id to the User that created this domain alias                                                                                      |
| deleted            | boolean   | Field that denotes if the domain alias is disabled or not                                                                                    |
| base\_directory    | string    | For landing pages, the directory that the domain alias will be published - Default is `/`                                                    |
| formatted\_domain  | string    | The hostname/domain where the domain alias is published, including the domain and subdomain (i.e `www.example.com`)                          |
| formatted\_url     | string    | Read-only field that formats the domain, base directory and scheme (i.e. `https://www.example.com/`)                                         |
| domain             | string    | The domain part of the `formatted_domain` (i.e. `www.example.com`)                                                                           |
| preview\_url       | string    | Preview URL for this domain alias. Should always be available regardless of published status                                                 |
| partner\_alias\_id | string    | Unique ID reference to partner IDs                                                                                                           |
| language\_code     | string    | The default language (plus specific region) for the domain alias. Similar to the values that browsers send. Examples: `en`, `en-us`          |
| custom\_fields     | object    | Custom field values assigned to the domain alias. This extends the parent Site's custom fields so only translated fields need to be provided |
| added              | timestamp | Date and time domain alias was created                                                                                                       |
| modified           | timestamp | Date and time domain alias was modified                                                                                                      |

#### Example object:

```javascript
{
    "added": "2013-06-19T11:17:13",
    "base_directory": "/succursale/location-name/",
    "custom_fields": {
        "headline": "Emplacement de la marque"
    },
    "deleted": false,
    "domain": "www.brandname.ca",
    "formatted_domain": "www.brandname.ca",
    "formatted_url": "https://www.brandname.ca/succursale/location-name/",
    "id": 12345,
    "language_code": "fr",
    "modified": "2014-01-28T13:20:13",
    "partner_alias_id": "fr-locationpage-55555555",
    "preview_url": "http://www.brandname.ca.whitelabel.cloudbackend.net/succursale/location-name/",
    "site_id": 55555,
    "trace_id": null,
    "user_id": 248114
}
```

## Create a domain alias

`POST /api/v2/domain_aliases/`

| Attribute         |
| ----------------- |
| formatted\_domain |
| site\_id          |
| language\_code    |

## List domain aliases

List all domain aliases including active and deleted

```
GET /api/v2/domain_aliases/
```

List all domain aliases associated with a Site ID

```
GET /api/v2/domain_aliases/?site_id=12345
```

### Parameters

| Name            | Type      | Description                                                   |
| --------------- | --------- | ------------------------------------------------------------- |
| `language_code` | `string`  | Filter for domain aliases with a matching locale              |
| `site_id`       | `integer` | Filter for domain aliases associated with a particular `Site` |

### Response

```javascript
{
  "meta": {
    "limit": 20,
    "next": "/api/v2/domain_aliases/?limit=20&offset=20",
    "offset": 0,
    "previous": null,
    "total_count": 154
  },
  "objects": [
    {
      "added": "2013-06-19T11:17:13",
      "base_directory": "/succursale/location-name/",
      "deleted": false,
      "domain": "www.brandname.ca",
      "formatted_domain": "www.brandname.ca",
      "formatted_url": "https://www.brandname.ca/succursale/location-name/",
      "id": 12345,
      "language_code": "fr",
      "modified": "2014-01-28T13:20:13",
      "partner_alias_id": "fr-locationpage-55555555",
      "preview_url": "http://www.brandname.ca.whitelabel.cloudbackend.net/succursale/location-name/",
      "site_id": 55555,
      "trace_id": null,
      "user_id": 248114
    },
    ....
  ]
}
```

## Get a single domain alias

Fetch the Domain alias detail using the `DomainAlias.id`

```
GET /api/v2/domain_aliases/:id/
```

## Updating a domain alias

```
PUT /api/v2/domain_aliases/:id/
```

You can `PUT` a partial or full object to the detail endpoint to update/change values on the Domain alias object. If using a partial object, you must insure that the primary domain alias `id` is part of the payload.

## Disabling / enabling a domain alias

### Disabling a domain alias

To disable an active domain alias and clear all cache references to the domain, use the `DELETE` method on the Domain alias detail endpoint.

```
DELETE /api/v2/domain_aliases/:id/
```

### Enabling a domain alias

To enable a currently disabled domain alias, you will set the param for `deleted` to `False` using the [Update endpoint](#updating-a-domain-alias)