Skip to content

Latest commit

 

History

History
307 lines (245 loc) · 8.5 KB

server-pools-api.rst

File metadata and controls

307 lines (245 loc) · 8.5 KB
Raw

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode

Server Pools API

https://blueprints.launchpad.net/designate/+spec/server-pools-api

This spec outlines the API changes needed for Server Pools. It is part of a larger group of specs describing the design of Designate Server Pools. The main blueprint is located here.

Problem description

Server Pools will need to be created, read, updated and deleted. An API needs to exist in order to carry out these operations.

Proposed change

This spec defines in detail the API changes needed for Server Pools.

API Changes

API Details: Create/List/Patch/Delete Pools

Tip

These should all be restricted to admins for general usage.

Verb Resource Description
GET /pools Returns all pools
GET /pools/{pool_id} Returns a specific pool with additional details
POST /pools Creates a new pool
PATCH /pools/{pool_id} Updates the pool with data in the request
DELETE /pools/{pool_id} Deletes the pool

GET /v2/pools

When no id is specified, all pools are returned. No body is provided in the request.

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

{
    "pools": [
        {
            "name": "US Pool 1",
            "id": "cf1fafc0-f2f0-11e3-ac10-0800200c9a66",
            "links": {
                "self" : "/v2/pools/cf1fafc0-f2f0-11e3-ac10-0800200c9a66"
            },
            "created_at": "2014-09-09T19:34:21.819615",
            "updated_at": null
        },
        {
            "name": "US Pool 2",
            "id": "cddda8f0-f558-11e3-a3ac-0800200c9a66",
            "links": {
                "self" : "/v2/pools/cddda8f0-f558-11e3-a3ac-0800200c9a66"
            },
            "created_at": "2014-09-09T19:34:21.819615",
            "updated_at": null
        }
    ],
    "links": {
        "self": "/v2/pools"
    }
}

GET /v2/pools/{pool_id}

When an id is provided in the url, the specific pool is returned with more detail. No body is provided in the request.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Location: /v2/pools/cf1fafc0-f2f0-11e3-ac10-0800200c9a66

{
    "pool": {
        "name": "US Pool 1",
        "id": "cf1fafc0-f2f0-11e3-ac10-0800200c9a66",
        "attributes": {
            "geo-ip": true,
            "anycast": false,
            "scope": public,
        },
        "pool_servers": [
            "1.2.3.4:53",
            "5.4.3.2:53"
        ],
        "nameservers": [
            {"priority": 1, "hostname": "ns1.example.com."},
            {"priority": 2, "hostname": "ns2.example.com."}
        ],
        "project_id": "<uuid>",
        "provisioner": "unmanaged",
        "created_at": "2014-09-04T19:34:20.819723",
        "updated_at": null
    },
    "links": {
        "self": "/v2/pools/cf1fafc0-f2f0-11e3-ac10-0800200c9a66"
    }
}

POST /v2/pools/

When a new Pool is created, the user must supply the name and scope. Initially, only "public" scope is supported. The other values shown here are optional. If the name is the same as an existing Pool, the return code will be 409 Conflict.

Request

HTTP/1.1
Content-Type: application/json; charset=UTF-8
Location: /v2/pools/

{
    "pool": {
        "name": "US Pool 3",
        "attributes": {
            "scope": public
        },
        "pool_servers": [
            "10.11.12.13:53",
            "13.12.11.10:53"
        ],
        "nameservers": [
            {"priority": 1, "hostname": "ns1.example.com."}
            {"priority": 2, "hostname": "ns2.example.com."}
        ]
    }
}

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: /v2/pools/

{
    "pool": {
        "name": "US Pool 3",
        "id": "cf1fafc0-f2f0-11e3-ac10-0800200c81a5",
        "attributes": {
            "scope": public,
        }
        "pool_servers": [
            "10.11.12.13:53",
            "13.12.11.10:53"
        ],
        "nameservers": [
            {"priority": 1, "hostname": "ns1.example.com."},
            {"priority": 2, "hostname": "ns2.example.com."}
        ],
        "created_at": "2014-09-04T19:34:20.819723",
        "updated_at": null
    },
    "links": {
        "self": "/v2/pools/cf1fafc0-f2f0-11e3-ac10-0800200c81a5"
    }
}

PATCH /v2/pools/{pool_id}

To modify a Pool, a PATCH request is submitted. If it is successful, a 200 is returned.

Request

HTTP/1.1
Content-Type: application/json; charset=UTF-8
Location: /v2/pools/cf1fafc0-f2f0-11e3-ac10-0800200c81a5

{
    "pool": {
        "pool_servers": [
            "4.5.6.7:53"
        ]
    }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Location: /v2/pools/cf1fafc0-f2f0-11e3-ac10-0800200c81a5

{
    "pool": {
        "name": "US Pool 3",
        "id": "cf1fafc0-f2f0-11e3-ac10-0800200c81a5",
        "attributes": {
            "scope": public,
        },
        "pool_servers": [
            "10.11.12.13:53",
            "13.12.11.10:53",
            "4.5.6.7:53"
        ],
        "nameservers": [
            {"priority": 1, "hostname": "ns1.example.com."},
            {"priority": 2, "hostname": "ns2.example.com."}
        ],
        "created_at": "2014-09-04T19:34:20.819723",
        "updated_at": "2014-09-10T19:33:10.819555"
    },
    "links": {
        "self": "/v2/pools/cf1fafc0-f2f0-11e3-ac10-0800200c81a5"
    }
}

DELETE /v2/pools/{pool_id}

When deleting a Pool, the user must supply the id in the url. The request body and return body are empty. A 204 is returned

HTTP/1.1 204 No Content Content-Type: application/json; charset=UTF-8 Location: /v2/pools/cf1fafc0-f2f0-11e3-ac10-0800200c81a5

Central Changes

The pool calls will have to be added to central to allow the CRUD of Server Pools.

Storage Changes

The pool calls will have to be added to storage. The new tables are described in a different spec.

Implementation

Assignee(s)

Primary assignee:

https://launchpad.net/~betsy-luzader

Milestones

Target Milestone for completion:

Kilo

Work Items

  • Create pools controller and view
  • Add the calls to Central
  • Add the calls to Storage
  • Write tests

Dependencies