Difference between revisions of "Designate/Blueprints/Filtering API"
m (→Overview) |
m (→Filtering Clarification) |
||
Line 21: | Line 21: | ||
− | NOTE: Filtering and searching are two completely different features and will be addressed separately. | + | NOTE: Filtering and searching are two completely different features and will be addressed separately. SEARCH involves the ability to compile a list of results from storage, possibly drawing from many different places (for example, finding all of a tenant's A records with a certain IP address). FILTERING only involves further restricting the standard queries that are offered by the API (for example, '''/zones''', '''/zones/{id}/recordsets''', etc.). |
You can find the spec for search [[Designate/Blueprints/Search_API|here]]. | You can find the spec for search [[Designate/Blueprints/Search_API|here]]. |
Revision as of 21:13, 25 June 2014
Contents
Overview
Gerrit Patch | [] |
---|---|
Launchpad Blueprint | [1] |
Filtering provides the ability to qualify the result set returned by a query to the designate api. It will ultimately be available on all collections - zones, record sets, rdata of record sets, and pools.
Filtering will be controlled using query parameters which match the name of the attribute being filtered. It is *not* required that all attributes are available as filter targets, but the majority will be.
Filters are either an exact match or substring match. Wildcard and regular expression matching may be introduced in a later revision of the v2 API, so long as the implementation is backward compatible. For now, substring matching should be restricted to right substrings only (i.e. abc.c% would match abc.co. and abc.com.).
If the filtering request is successful, the resources that pass the filter criteria are returned as well as links for retrieving more details.
Pagination of results will take advantage of proposed Designate pagination (https://blueprints.launchpad.net/designate/+spec/pagination)
Filtering Clarification
NOTE: Filtering and searching are two completely different features and will be addressed separately. SEARCH involves the ability to compile a list of results from storage, possibly drawing from many different places (for example, finding all of a tenant's A records with a certain IP address). FILTERING only involves further restricting the standard queries that are offered by the API (for example, /zones, /zones/{id}/recordsets, etc.).
You can find the spec for search here.
Completion History
This spec has been partially implemented. The following is a list of features that have been completed as well as a list of features that are pending. In addition, to further clarify the difference between filtering and searching, a list of features that is exclusively part of searching is included.
Completed
- Basic filtering for:
- Blacklists: pattern
- Records: data
- Recordsets: name, type, TTL
- TLDs: name
- Zones: name
- Substring search using SQL pattern matching
Pending
- Restrictions on substring search (currently substring searching is unrestricted)
- Add more attributes for filtering
- Changes to record/recordset filtering after the recordset API change
Search features, will NOT be implemented here
- Searching for other parameters across all tenants in general
- Done by adding an all_tenants option
- Searching for recordsets by IP address across all tenants
API Changes
The large part of the Filtering API will be extensions of existing GET APIs on existing Resources (zones, record sets, rdata of record sets, and pool) to specify filters using query parameters.
High level description of implementation logic
Following is a high level description of the flow of logic. More detailed request/response formats are specified in the examples and use case section below.
1. User issues a search request on a resource with appropriate filters. Optionally, two other parameters can be specified – match-type (exact/substr) and all_tenants (true/false).
For example: GET /v2/zones?name=example.com&match-type=exact HTTP/1.1
Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_*****
2. In middleware.py:KeystoneMiddleware::process_request(), during the construction of DesignateContext
- determined that all_tenants is set to True signaling intent to perform this operation on all tenants
- perform policy check (in the API before we pass on to Central)
- if confirmed that the user has this right to perform the operation across all tenants,
- set context.all_tenants=True
- let the request proceed to Central
- if user cannot be confirmed to have the right to perform the operation across all tenants, reject the request with appropriate message
- if confirmed that the user has this right to perform the operation across all tenants,
- perform policy check (in the API before we pass on to Central)
- determined that all_tenants is set to True signaling intent to perform this operation on all tenants
3. In Central:
- issue the correct SQL query against the Storage database using the request query parameter as WHERE clause value.
- return to designate-api
4. Api - return the result set.
API Details
Privileged user searching for a specified zone name across all tenants
A Privileged user searching for a specified recordset by name within a specified zone for a given tenant
This is the ability to search for a record by name in a given zone that might have lots of records. By definition, a specific zone belongs to one tenant so even a privileged user (support/admin) is able to search only within any specific account but not across all accounts at the same time.
Request:
GET zones/{zone-id}/recordsets?name=example&match-type=substr Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_***** X-Tenant-ID: 44441
Response:
{ "recordsets": [{ "id": "9e27811d-0320-4179-abb7-0e00e371e25b", "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", "name": "www.example.org.", "type": "A", "ttl": 3600, "status": "ACTIVE", "version": 1, "created_at": "...", "updated_at": null, "links": { "self": "https://dns.provider.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets/9e27811d-0320-4179-abb7-0e00e371e25b" } }, { "id": "dedf6879-fd9a-41d6-a7c2-eeac316fa7b3", "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", "name": "_xmpp-server._tcp.example.org.", "type": "SRV", "ttl": 3600, "status": "ACTIVE", "version": 1, "created_at": "...", "updated_at": null, "links": { "self": "https://dns.provider.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets/dedf6879-fd9a-41d6-a7c2-eeac316fa7b3" } }], "links": { "self": "https://dns.provider.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets", "next": "https://dns.provider.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets?marker=dedf6879-fd9a-41d6-a7c2-eeac316fa7b3" } }
A Customer searching for a specified recordset by name within a specified zone
A customer is able to search on zone that belongs to customer By definition, a specific zone belongs to one tenant. Besides, ordinary tenants are not privileged to perform any operation on any other tenant id.
Request:
GET zones/{zone-id}/recordsets?name=exam&match-type=substr Host: dns.provider.com Accept: application/json X-Auth-Token: KeyStoneAuth_***** X-Tenant-ID: 33377
Response:
{ "recordsets": [{ "id": "dedf6879-fd9a-41d6-a7c2-eeac316fa7b3", "zone_id": "986dba58-0043-4cc6-a1bb-69d5e86f3ca9", "name": "_xmpp-server._tcp.example.org.", "type": "SRV", "ttl": 3600, "status": "ACTIVE", "version": 1, "created_at": "...", "updated_at": null, "links": { "self": "https://dns.provider.com/v2/zones/986dba58-0043-4cc6-a1bb-69d5e86f3ca9/recordsets/dedf6879-fd9a-41d6-a7c2-eeac316fa7b3" } }], }
Database Changes
N/A