Designate/Blueprints/Search API
Contents
- 1 Overview
- 2 API Changes
- 2.1 One Per Change
- 2.1.1 Example of Call (HTTP Verb)
- 2.1.2 Privileged user searching in one tenant
- 2.1.3 A Customer searching across all tenants
- 2.1.4 A Customer searching in one tenant
- 2.1.5 A Privileged user searching for records pointing to a specific IP Address across all tenants
- 2.1.6 A Privileged user searching for records pointing to a specific IP Address in a given tenant
- 2.1.7 A Customer searching for records pointing to a specific IP Address across all tenants
- 2.1.8 A Customer searching for records pointing to a specific IP in the customer's own space
- 2.1 One Per Change
- 3 Database Changes
Overview
Right now, this spec is a VERY rough draft. It is mainly content from the Filtering API that has been moved into here because it didn't belong in the Filtering API.
Gerrit Patch | [] |
---|---|
Launchpad Blueprint | [] |
Summary
Quick overview of the change
API Changes
Search, like filtering, will be implemented as a URL option. For
Additionally, where applicable, privileged users (support and admin) will be able to perform searching across all tenants by specifying an additional parameter, all_tenants=true, in their GET requests.
Searching by address is a special case and has undergone much discussion. This is primarily because a tenant may want to search for an address over all of their records (which could be distributed among several recordsets, in several zones), or over an individual recordset. In addition, admins need to be able to search for an address over all tenants' records. Several solutions have been proposed, and a tentative approach is discussed below:
- Create a /records endpoint for admin use only, to search for addresses across all tenants. Use the original /zones/{id}/recordsets endpoint for individual tenants to search for an address within a single zone. Having tenants search for an address across all of their zones, however, is not clear. Perhaps the /records endpoint could be used for this, with an all_tenants option to differentiate between searching across one tenant and all tenants?
For illustration, below is a table showing a search for the IP address ADDR, constructed in the different ways posed above. All of these requests are GET requests.
One recordset (filtering) | Entire tenant (search) | All tenants (search) |
---|---|---|
/zones/{zone-id}/recordsets/{recordset-id}/records?address=ADDR | /records?address=ADDR | /records?address=ADDR&all_tenants=true |
List of changes to the HTTP API
One Per Change
Verb | Resource | Description |
---|---|---|
GET | /zones?name=example.com&match-type=exact&all_tenants=true | Return zones that have names that exactly match the specified filter (“name”) across all tenants. Note: Only admins and support can search across all tenants. |
GET | zones/{zone-id}/recordsets?name=example.com&match-type=substr | From the specified zone, return recordsets that have name that the specified filter (“name”) is a substring of. |
GET | /zones/{zone-id}/recordsets?address=10.1.2.3&match-type=exact | From the specified zone for this tenant, return Address recordsets that exactly match the specified IP address. |
GET | /zones/ipaddresses?address=172.192.112.82&match-type=exact&all_tenants=true | From all the zones belonging to all tenants, return Address recordsets that exactly match the specified IP address. |
GET | /zones/ipaddresses?address=172.192.112.82&match-type=exact | From all the zones belonging to this tenant, return Address recordsets that exactly match the specified IP address. |
GET,
PUT, PATH, POST, DELETE |
/zones/ipaddresses | No Op. |
PUT, PATH, POST, DELETE | /zones/ipaddresses?address=172.192.112.82 | No Op.
These should be done through /zone/{zone-id}/recordsets/ |
Example of Call (HTTP Verb)
Request:
GET /v2/zones?name=example.com&match-type=exact&all_tenants=true HTTP/1.1 Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_***** X-Tenant-ID:
Response:
{ "zone": { "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", "pool_id": "7d62d10d-3a16-4828-85dd-7b3fdc0ba989", "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", "name": "example.com.", "email": "joe@example.com.", "ttl": 7200, "serial": 1351800588, "status": "ACTIVE", "version": 1, "created_at": "...", "updated_at": null, "links": { "self": "https://dns.provider.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3" } } }
Privileged user searching in one tenant
Request:
GET /v2/zones?name=example.com&match-type=exact HTTP/1.1 Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_***** X-Tenant-ID: 12345
Response:
(Empty - this particular tenant does not have domain example.com):
{ "zone": { } }
A Customer searching across all tenants
Throw exception when policy check in API shows that tenant 1234 is not privileged to search across all tenants
A Customer searching in one tenant
Request:
GET /v2/zones?name=exp.com&match-type=exact HTTP/1.1 Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_***** X-Tenant-ID: 12345
Response:
{ "zone": { "id": "a66dba58-0043-4cc6-a1bb-69d5e86f3ca3", "pool_id": "6d62d10d-3a16-4828-85dd-7b3fdc0ba989", "project_id": "5335d1f0-f793-11e2-b778-0800200c9a66", "name": "exp.com.", "email": "jane@exp.com.", "ttl": 7200, "serial": 1351800588, "status": "ACTIVE", "version": 1, "created_at": "...", "updated_at": null, "links": { "self": "https://dns.provider.com/v2/zones/c86dba58-0043-4cc6-a1bb-69d5e86f3cc1" } } }
A Privileged user searching for records pointing to a specific IP Address across all tenants
Request:
GET /v2/zones/ipaddresses?address=172.192.112.82&match-type=exact&all_tenants=true HTTP/1.1 Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_***** X-Tenant-ID:
Response:
{ "records": [ { "type": "A", "address": "172.192.112.82", “id”: “9e27811d-0320-4179-abb7-0e00e371e25b”, "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", “name”: "www.example.org.", "links": { "self": "https://dns.provider.com/v2/zones/986dba58-0043-4cc6-a1bb-69d5e86f3ca9/recordsets/dedf6879-fd9a-41d6-a7c2-eeac316fa7b3" } }, { "type": "A", "address": "172.192.112.82", “id”: “4e27811d-0320-4179-abb7-0e00e371e25c”, "zone_id": "b46dba58-0043-4cc6-a1bb-69d5e86f3cc1", “name”: "exp.com.", "links": { "self": "https://dns.provider.com/v2/zones/436dba58-0043-4cc6-a1bb-69d5e86f3ca9/recordsets/dedf6879-fd9a-41d6-a7c2-eeac316fa7d2" } } ] }
A Privileged user searching for records pointing to a specific IP Address in a given tenant
Request:
GET /v2/zones/ipaddresses?address=172.192.112.82&match-type=exact HTTP/1.1 Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_***** X-Tenant-ID: 31476
Response:
{ "records": [ { "type": "A", "address": "172.192.112.82", “id”: “4e27811d-0320-4179-abb7-0e00e371e25c”, "zone_id": "b46dba58-0043-4cc6-a1bb-69d5e86f3cc1", “name”: "exp.com.", "links": { "self": https://dns.provider.com/v2/zones/436dba58-0043-4cc6-a1bb-69d5e86f3ca9/recordsets/dedf6879-fd9a-41d6-a7c2-eeac316fa7d2 } } ] }
A Customer searching for records pointing to a specific IP Address across all tenants
Exception - no customer can search across all tenants
A Customer searching for records pointing to a specific IP in the customer's own space
Request:
GET /v2/zones/ipaddresses?address=172.192.112.82&match-type=exact HTTP/1.1 Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_***** X-Tenant-ID: 44441
Response:
{ "records": [ { "type": "A", "address": "172.192.112.82", “id”: “9e27811d-0320-4179-abb7-0e00e371e25b”, "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", “name”: "www.example.org.", "links": { "self": "https://dns.provider.com/v2/zones/986dba58-0043-4cc6-a1bb-69d5e86f3ca9/recordsets/dedf6879-fd9a-41d6-a7c2-eeac316fa7b3" } } ] }
Database Changes
Description of Changes to DB schemas
eg -
Name | Data Type | Length | Nullable | Details |
---|---|---|---|---|
id | VARCHAR | 36 | False | Primary Key, Generated UUID |
name | VARCHAR | 255 | False | Domain name to be blacklisted |
version | INTEGER | - | False | Designate API version |
created_at | DATETIME | - | False | UTC time of creation |
updated_at | DATETIME | - | True | UTC time of creation |
description | VARCHAR | 160 | True | UTF-8 text field |