RESTful API

This document describes the API endpoints for the ddns-so service.

This document describes the RESTful API provided by `api.ddns.so` for resolving domain names and querying name records.

API Endpoint

https://api.ddns.so

Example

curl https://api.ddns.so/name/nameset.dot

Resolve Name

Resolve a name to get its records.

URL : /name/:name

Method : GET

Auth required : NO

Permissions required : None

Parameters

• name=[string] name to resolve (required)

Response

200 OK on success

{
  "result": "ok",
  "data": {
    "name": "john.dot",
    "name_hash": "0x...", 
    "records": {
      "avatar": "https://...",
      "twitter": "@john" 
    }
  }
}

Errors

• 404 Not Found if name is not found

• 500 Internal Server Error on any other error

Get Subdomains

Get paginated list of subdomains for a name.

URL : /subdomains/:name

Method : GET

Auth required : NO

Permissions required : None

Parameters

• name=[string] parent name

• before - Fetch subdomains before this name hash

• after - Fetch subdomains after this name hash

• limit - Maximum number of subdomains to return (default 50)

• order - Ordering of results - asc or desc (default asc)

Response

200 OK on success

{
  "result": "ok",
  "pagination": {
    "before": "acc.example.dot",
    "limit": 10,
    "order": "asc"
  },
  "subdomains": [
    {
      "name": "foo.example.dot",
      "nameHash": "0x123abc...",
      "owner": "0x456def..."
    },
    {
      "name": "bar.example.dot",
      "nameHash": "0x456def...",
      "owner": "0x789ghi..."
    }
  ]
}

Errors

• 404 Not Found if parent name not found

• 500 Internal Server Error on any other error

Reverse Resolution

Reverse resolve an address to get the name.

URL : /reverse/pns/:address for PNS

URL : /reverse/ens/:address for ENS

Method : GET

Auth required : NO

Permissions required : None

Parameters

• address=[string] address to reverse resolve

Response

200 OK on success

{

  "result": "ok",

  "address": "0x1234...",

  "name": "john.dot"

}

Errors

• 404 Not Found if address not found

• 500 Internal Server Error on any other error