deb-designate/doc/source/rest/v2/blacklists.rst

Blacklists

Overview

The blacklist entries are used to manage blacklisted zones. If a zone is blacklisted, then it cannot be used to create a zone. By default, only an admin can manage these entries. Blacklisted zones are stored as a regular expression (regex) pattern in the database in the blacklists table.

Blacklist Checks

Every time a new zone is created, that domain name is checked against the blacklisted zones in the database. If it matches the regex pattern, then a 400 is returned with the message "Blacklisted domain name". If there is no match, then the zone is created. When a new blacklisted pattern is added, it will catch any matching new zones, but it does not check for existing zones that match the blacklisted pattern.

Regular Expressions

Any valid regular expression may be added to the blacklists table. Here are some examples:

1. ^example\\.com\\.$

   This will block the "example.com." domain, but will not block any sub-domains, e.g. "my.example.com." or anything else containing example.com, such as, "myexample.com."

2. ^([A-Za-z0-9_\-]+\\.)*example\\.com\\.$

   This will block "example.com." and all sub-domains, e.g. "my.example.com.", but anything else containing example.com, will not be blocked, such as, "myexample.com."

NOTE: When using regular expressions in json, the '\' character needs to be escaped with an additional '\', so it needs to be written as "^example\\.com\\.$"

Create a Blacklist

Create a blacklist. pattern is the only entry that is required. The domain name part of the pattern should end in a period (.).'

Example request:

POST /blacklists HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json

{
  "pattern" : "^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
  "description" : "This is a blacklisted domain."
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: 127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd

{
    "description":"This is a blacklisted domain.",
    "links":{
        "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
    },
    "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
    "created_at":"2014-03-11T21:54:57.000000",
    "updated_at":null,
    "id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
}

form created_at

timestamp

form updated_at

timestamp

form pattern

blacklist regular expression

form id

uuid

form description

UTF-8 text field

form links

links to traverse the list

statuscode 201

Created

statuscode 401

Access Denied

statuscode 400

Invalid Object

statuscode 409

Duplicate Blacklist

Get a Blacklist

Lists a particular Blacklisted domain

Example request:

GET /blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "description":"This is a blacklisted domain.",
  "links":{
    "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
  },
  "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
  "created_at":"2014-03-11T21:54:57.000000",
  "updated_at":null,
  "id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
}

form created_at

timestamp

form updated_at

timestamp

form pattern

blacklist regular expression

form id

uuid

form description

UTF-8 text field

form links

links to traverse the list

statuscode 200

OK

statuscode 401

Access Denied

statuscode 404

Blacklist not found

List Blacklists

Lists all blacklists

Example request:

GET /blacklists HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "blacklists":[
    {
    "description": "This is a blacklisted domain.",
    "links":{
      "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
    },
    "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
    "created_at":"2014-03-11T21:54:57.000000",
    "updated_at":null,
    "id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
    },
    {
      "description": null,
      "links":{
        "self":"http://127.0.0.1:9001/v2/blacklists/61140aff-e2c8-488b-9bf4-da710ec8732b"
      },
      "pattern" : "^examples\\.com\\.$",
      "created_at":"2014-03-07T21:05:59.000000",
      "updated_at":null,
      "id":"61140aff-e2c8-488b-9bf4-da710ec8732b"
    }
  ],
  "links":{
    "self":"http://127.0.0.1:9001/v2/blacklists"
  }
}

form created_at

timestamp

form updated_at

timestamp

form pattern

blacklist regular expression

form id

uuid

form description

UTF-8 text field

form links

links to traverse the list

statuscode 200

OK

statuscode 401

Access Denied

Update a Blacklist

updates a blacklist

Example request:

PATCH blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json

{
  "pattern" : "^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
  "description" : "Updated the description"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "description":"Updated the pattern to catch subdomains",
  "links":{
    "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
  },
  "created_at":"2014-03-11T21:54:57.000000",
  "updated_at":"2014-03-13T16:49:32.117187",
  "id":"c47229fb-0831-4b55-a5b5-380d361be4bd",
  "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$"
}

form created_at

timestamp

form updated_at

timestamp

form pattern

blacklist regular expression pattern

form id

uuid

form description

UTF-8 text field

form links

links to traverse the list

statuscode 200

OK

statuscode 401

Access Denied

statuscode 404

Blacklist not found

statuscode 409

Duplicate Blacklist

Delete a Blacklist

delete a blacklist

Example request:

DELETE /blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 204 No Content
Content-Type: application/json; charset=UTF-8
Content-Length: 0

statuscode 204

No Content

statuscode 401

Access Denied

statuscode 404

Blacklist not found