Difference between revisions of "DNS API"

From CMU ITSC Network
(Created page with "Hello")
 
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
Hello
+
== Authentication ==
 +
Authenticate with [https://oauth.cmu.ac.th CMU OAuth] to get access token then use as "bearer token" in "Authorization" Header on every request.
 +
 
 +
== REST API ==
 +
'''https://dns-api.cmu.ac.th'''
 +
== Method ==
 +
=== List domain ===
 +
'''Request'''
 +
<syntaxhighlight lang=html>
 +
GET /domains HTTP/1.1
 +
Host: dns-api.cmu.ac.th
 +
Authorization: Bearer hKm1BTuXj4U7rGChx1eWKSb8bc6Wx1uz
 +
</syntaxhighlight>
 +
'''Response'''
 +
<syntaxhighlight lang=json>
 +
[
 +
    {
 +
        "domain": "cnoc.cmu.ac.th"
 +
    },
 +
    {
 +
        "domain": "eng.cmu.ac.th"
 +
    },
 +
    {
 +
        "domain": "reg.cmu.ac.th"
 +
    }
 +
]
 +
</syntaxhighlight>
 +
 
 +
=== List records in domain ===
 +
'''Request'''
 +
<syntaxhighlight lang=html>
 +
GET /domains/:domain HTTP/1.1
 +
Host: dns-api.cmu.ac.th
 +
Authorization: Bearer hKm1BTuXj4U7rGChx1eWKSb8bc6Wx1uz
 +
</syntaxhighlight>
 +
'''Parameter'''
 +
<syntaxhighlight lang=html>
 +
:domain = domain name e.g. cnoc.cmu.ac.th
 +
</syntaxhighlight>
 +
'''Response'''
 +
<syntaxhighlight lang=json>
 +
[
 +
    {
 +
        "id": 110,
 +
        "domain_id": 1,
 +
        "name": "cnoc.cmu.ac.th",
 +
        "type": "A",
 +
        "content": "202.28.249.45",
 +
        "ttl": 3600,
 +
        "prio": 0,
 +
        "change_date": null,
 +
        "disabled": 0,
 +
        "ordername": null,
 +
        "auth": 1
 +
    },
 +
    {
 +
        "id": 1707,
 +
        "domain_id": 1,
 +
        "name": "xxx.cnoc.cmu.ac.th",
 +
        "type": "A",
 +
        "content": "5.6.7.8",
 +
        "ttl": 3600,
 +
        "prio": 0,
 +
        "change_date": null,
 +
        "disabled": 0,
 +
        "ordername": null,
 +
        "auth": 1
 +
    },
 +
    {
 +
        "id": 1708,
 +
        "domain_id": 1,
 +
        "name": "xxx1.cnoc.cmu.ac.th",
 +
        "type": "A",
 +
        "content": "9.0.43.2",
 +
        "ttl": 3600,
 +
        "prio": 0,
 +
        "change_date": null,
 +
        "disabled": 0,
 +
        "ordername": null,
 +
        "auth": 1
 +
    },
 +
    {
 +
        "id": 1709,
 +
        "domain_id": 1,
 +
        "name": "yyy.cnoc.cmu.ac.th",
 +
        "type": "A",
 +
        "content": "2.8.6.3",
 +
        "ttl": 3600,
 +
        "prio": 0,
 +
        "change_date": null,
 +
        "disabled": 0,
 +
        "ordername": null,
 +
        "auth": 1
 +
    }
 +
]
 +
</syntaxhighlight>
 +
 
 +
=== Add record ===
 +
'''Request'''
 +
<syntaxhighlight lang=html>
 +
POST /domains/:domain HTTP/1.1
 +
Host: dns-api.cmu.ac.th
 +
Content-Type: application/json
 +
Authorization: Bearer hKm1BTuXj4U7rGChx1eWKSb8bc6Wx1uz
 +
</syntaxhighlight>
 +
 
 +
'''Parameter'''
 +
<syntaxhighlight lang=html>
 +
:domain = domain name e.g. cnoc.cmu.ac.th
 +
</syntaxhighlight>
 +
 
 +
'''Body Schema'''
 +
<syntaxhighlight lang=json>
 +
{
 +
  "title" : "dns record",
 +
  "description" : "properties required to creat a dns record",
 +
  "type" : "object",
 +
  "properties" : {
 +
    "name" : {
 +
      "type" : "string",
 +
      "description" : "domain name record",
 +
      "minLength" : 1,
 +
      "pattern" : "cmu.ac.th$"
 +
    },
 +
    "type" : {
 +
      "type" : "string",
 +
      "description" : "domain name record type",
 +
      "enum" : ["A","AAAA","MX","CNAME","TXT"]
 +
    },
 +
    "content" : {
 +
      "type" : "string",
 +
      "description" : "domain name record content",
 +
      "minLength" : 1
 +
    },
 +
    "ttl" : {
 +
      "type" : "integer",
 +
      "description" : "domain name record time to live",
 +
      "minimum" : 3600
 +
    },
 +
    "prio" : {
 +
      "type" : "integer",
 +
      "description" : "domain name record piority",
 +
      "minimum" : 0
 +
    },
 +
    "autoPTR" : {
 +
      "type" : "boolean",
 +
      "description" : "auto create reverse lookup record for A record within CMU ip subnet"
 +
    }
 +
  },
 +
  "additionalProperties": false,
 +
  "required": ["name", "type", "content", "ttl", "prio"]
 +
}
 +
</syntaxhighlight>
 +
'''Body Example'''
 +
<syntaxhighlight lang=json>
 +
{
 +
"name" : "www1.cnoc.cmu.ac.th",
 +
"type" : "A",
 +
"content" : "1.11.111.1",
 +
"ttl" : 3600,
 +
"prio" : 0
 +
}
 +
</syntaxhighlight>
 +
'''Response'''
 +
<syntaxhighlight lang=json>
 +
{
 +
    "msg": "record added",
 +
    "status": "OK",
 +
    "record": {
 +
        "name": "www1.cnoc.cmu.ac.th",
 +
        "type": "A",
 +
        "content": "1.11.111.1",
 +
        "ttl": 3600,
 +
        "prio": 0,
 +
        "domain_id": 1
 +
    }
 +
}
 +
</syntaxhighlight>
 +
 
 +
=== Delete record ===
 +
'''Request'''
 +
<syntaxhighlight lang=html>
 +
DELETE /domains/cnoc.cmu.ac.th/:id HTTP/1.1
 +
Host: dns-api.cmu.ac.th
 +
Authorization: Bearer 39JxUzTv9EUMBpnsCcdBQmeNzhQK1SY9
 +
</syntaxhighlight>
 +
 
 +
'''Parameter'''
 +
<syntaxhighlight lang=html>
 +
:id = record id
 +
</syntaxhighlight>
 +
 
 +
'''Response'''
 +
<syntaxhighlight lang=json>
 +
{
 +
    "msg": "delete 1 record with PTR."
 +
}
 +
</syntaxhighlight>

Latest revision as of 11:13, 6 May 2018

Authentication

Authenticate with CMU OAuth to get access token then use as "bearer token" in "Authorization" Header on every request.

REST API

https://dns-api.cmu.ac.th

Method

List domain

Request

GET /domains HTTP/1.1
Host: dns-api.cmu.ac.th
Authorization: Bearer hKm1BTuXj4U7rGChx1eWKSb8bc6Wx1uz

Response

[
    {
        "domain": "cnoc.cmu.ac.th"
    },
    {
        "domain": "eng.cmu.ac.th"
    },
    {
        "domain": "reg.cmu.ac.th"
    }
]

List records in domain

Request

GET /domains/:domain HTTP/1.1
Host: dns-api.cmu.ac.th
Authorization: Bearer hKm1BTuXj4U7rGChx1eWKSb8bc6Wx1uz

Parameter

:domain = domain name e.g. cnoc.cmu.ac.th

Response

[
    {
        "id": 110,
        "domain_id": 1,
        "name": "cnoc.cmu.ac.th",
        "type": "A",
        "content": "202.28.249.45",
        "ttl": 3600,
        "prio": 0,
        "change_date": null,
        "disabled": 0,
        "ordername": null,
        "auth": 1
    },
    {
        "id": 1707,
        "domain_id": 1,
        "name": "xxx.cnoc.cmu.ac.th",
        "type": "A",
        "content": "5.6.7.8",
        "ttl": 3600,
        "prio": 0,
        "change_date": null,
        "disabled": 0,
        "ordername": null,
        "auth": 1
    },
    {
        "id": 1708,
        "domain_id": 1,
        "name": "xxx1.cnoc.cmu.ac.th",
        "type": "A",
        "content": "9.0.43.2",
        "ttl": 3600,
        "prio": 0,
        "change_date": null,
        "disabled": 0,
        "ordername": null,
        "auth": 1
    },
    {
        "id": 1709,
        "domain_id": 1,
        "name": "yyy.cnoc.cmu.ac.th",
        "type": "A",
        "content": "2.8.6.3",
        "ttl": 3600,
        "prio": 0,
        "change_date": null,
        "disabled": 0,
        "ordername": null,
        "auth": 1
    }
]

Add record

Request

POST /domains/:domain HTTP/1.1
Host: dns-api.cmu.ac.th
Content-Type: application/json
Authorization: Bearer hKm1BTuXj4U7rGChx1eWKSb8bc6Wx1uz

Parameter

:domain = domain name e.g. cnoc.cmu.ac.th

Body Schema

{
  "title" : "dns record",
  "description" : "properties required to creat a dns record",
  "type" : "object",
  "properties" : {
    "name" : {
      "type" : "string",
      "description" : "domain name record",
      "minLength" : 1,
      "pattern" : "cmu.ac.th$"
    },
    "type" : {
      "type" : "string",
      "description" : "domain name record type",
      "enum" : ["A","AAAA","MX","CNAME","TXT"]
    },
    "content" : {
      "type" : "string",
      "description" : "domain name record content",
      "minLength" : 1
    },
    "ttl" : {
      "type" : "integer",
      "description" : "domain name record time to live",
      "minimum" : 3600
    },
    "prio" : {
      "type" : "integer",
      "description" : "domain name record piority",
      "minimum" : 0
    },
    "autoPTR" : {
      "type" : "boolean",
      "description" : "auto create reverse lookup record for A record within CMU ip subnet"
    }
  },
  "additionalProperties": false,
  "required": ["name", "type", "content", "ttl", "prio"]
}

Body Example

{ 
	"name" : "www1.cnoc.cmu.ac.th",
	"type" : "A",
	"content" : "1.11.111.1",
	"ttl" : 3600,
	"prio" : 0
}

Response

{
    "msg": "record added",
    "status": "OK",
    "record": {
        "name": "www1.cnoc.cmu.ac.th",
        "type": "A",
        "content": "1.11.111.1",
        "ttl": 3600,
        "prio": 0,
        "domain_id": 1
    }
}

Delete record

Request

DELETE /domains/cnoc.cmu.ac.th/:id HTTP/1.1
Host: dns-api.cmu.ac.th
Authorization: Bearer 39JxUzTv9EUMBpnsCcdBQmeNzhQK1SY9

Parameter

:id = record id

Response

{
    "msg": "delete 1 record with PTR."
}