Jump to: navigation, search

Difference between revisions of "Designate/Blueprints/Search API"

(Created page with "== Overview == Right now, this spec is a '''very''' rough draft. It is mainly content from the Filtering API that has been moved into...")
 
m (Overview)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
  
Right now, this spec is a '''very''' rough draft.  It is mainly content from the [[/Designate/Blueprints/Filtering_API|Filtering API]] that has been moved into here because it didn't belong in the Filtering API.
+
Right now, this spec is a VERY rough draft.  It is mainly content from the [[/Designate/Blueprints/Filtering_API|Filtering API]] that has been moved into here because it didn't belong in the Filtering API.
  
 
{| class="wikitable"
 
{| class="wikitable"

Revision as of 20:38, 25 June 2014

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

Additionally, where applicable, privileged users (support and admin) will be able to perform filtering across all tenants by specifying an additional parameter, all_tenants=true, in their GET requests.

Filtering 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, some of which are listed 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?
  • Create a /search/records endpoint. Similar to point 1 otherwise. The benefit of this would be that other resources could be searched for this way, and all kept under a common subdomain: e.g. /search/zones, /search/blacklists, etc.
  • Create a new sub-resource of zones ipaddresses, and create a /zones/ipaddresses endpoint. The only valid filter parameter on this resource would be “address” and only the GET operation will be valid on this resource (other operations will be No-Ops on this resource). One of the justifications for this sub-resource is that a given IP address could be pointed to from zones owned by different tenants and therefore we cannot use the existing /zones/{zone-id}/recordsets endpoint to perform filtering across multiple zones.

For illustration, below is a table showing a filter for the IP address ADDR, constructed in the different ways posed above. All of these requests are GET requests.

One recordset Entire tenant All tenants
/zones/{z-id}/recordsets/{rs-id}/records?address=ADDR /records?address=ADDR /records?address=ADDR&all_tenants=true
/zones/{z-id}/recordsets/{rs-id}/records?address=ADDR /search/records?address=ADDR /search/records?address=ADDR&all_tenants=true
/zones/{z-id}/recordsets/{rs-id}/records?address=ADDR /zones/ipaddresses?address=ADDR /zones/ipaddresses?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