designate/doc/source/rest.rst
Eric Larson 410183a5e1 A small intro to the REST API
The goal here is to communicate what the docs represent and how to
translate the examples to actionable code.

Change-Id: I8aa49c034eb823b30620621758979beabd8c880b
2015-02-24 15:11:40 -06:00

1.6 KiB

REST API Documentation

Intro

In the REST API examples, HTTP requests are defined as raw HTTP. For example:

POST /v2/pools HTTP/1.1          # The HTTP Method, Path and HTTP Version
Accept: application/json         # Headers
Content-Type: application/json

{                                # The rest is the body of request
  "pool": {
    "name": "Example Pool",
    "nameservers": [
      "ns1.example.org."
    ]
  }
}

With this info we can make this request using the cURL tool. We'll assume we are running Designate on localhost.

curl -X POST -i \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '{"name": "ns1.example.org."}' \
     http://localhost:9001/v1/servers

The -i flag is used to dump the response headers as well as the response body.

The cURL tool is extremely robust. Please take a look at the cURL tutorial for more info.

API Versions

The API has 2 versions - V1 and V2.

V1 API

rest/v1/servers rest/v1/domains rest/v1/records rest/v1/diagnostics rest/v1/quotas rest/v1/reports rest/v1/sync

V2 API

rest/v2/collections rest/v2/zones rest/v2/recordsets rest/v2/tlds rest/v2/blacklists rest/v2/quotas