Skip to content

Commit

Permalink
Merge pull request #5 from DK-Hostmaster/3.0-candidate
Browse files Browse the repository at this point in the history 
3.0 candidate
  • Loading branch information
@jonasbn
jonasbn committed Nov 25, 2019
2 parents 356098e + 464bd40 commit f37c208
Showing 1 changed file with 55 additions and 197 deletions.
252 changes: 55 additions & 197 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@

![GitHub Workflow build status badge markdownlint](https://github.com/DK-Hostmaster/whois-rest-service-specification/workflows/Markdownlint%20Workflow/badge.svg)

2019-11-19
Revision: 2.1
2019-11-25
Revision: 3.0

**PLEASE NOTE THAT THIS SERVICE IS CURRENTLY IN BETA AND CHANGES MIGHT BE IMPLEMENTED WHICH BREAK BACKWARDS COMPATIBILITY**

# Table of Contents

<!-- MarkdownTOC bracket=round levels="1,2,3, 4" indent=" " autolink="true" -->
<!-- MarkdownTOC bracket=round levels="1,2,3, 4" indent=" " autolink="true" autoanchor="true" -->

- [Introduction](#introduction)
- [About this Document](#about-this-document)
Expand All @@ -32,17 +32,13 @@ Revision: 2.1
- [domain list](#domain-list)
- [API](#api-1)
- [Example](#example-1)
- [handle](#handle)
- [API](#api-2)
- [Example](#example-2)
- [host](#host)
- [API](#api-3)
- [Example](#example-3)
- [query](#query)
- [API](#api-4)
- [Domain Example](#domain-example)
- [Host Example](#host-example)
- [Handle Example](#handle-example)
- [Resources](#resources)
- [Mailing list](#mailing-list)
- [Issue Reporting](#issue-reporting)
Expand All @@ -62,7 +58,7 @@ The WHOIS RESTful service is optimized for structured querying in contrast to it
<a id="about-this-document"></a>
# About this Document

This specification describes version 2 (2.X.X) of the DK Hostmaster WHOIS RESTful service implementation. Future releases will be reflected in updates to this specification, please see the document history section below.
This specification describes version 3 (3.X.X) of the DK Hostmaster WHOIS RESTful service implementation. Future releases will be reflected in updates to this specification, please see the document history section below.
The document describes the current DK Hostmaster WHOIS RESTful service implementation, for more general documentation on the used protocols and additional information please refer to the RFCs and additional resources in the References and Resources chapters below.
Any future extensions and possible additions and changes to the implementation are not within the scope of this document and will not be discussed or mentioned throughout this document.

Expand All @@ -76,6 +72,11 @@ This document is copyright by DK Hostmaster A/S and is licensed under the MIT Li
<a id="document-history"></a>
## Document History

- 3.0 2019-11-25
- Support for queries using user handles are no longer supported and the API endpoint `https://whois-api.dk-hostmaster.dk/handle/{userid}` has been removed
- Support for queries using roles are not longer supported and the API endpoint `https://whois-api.dk-hostmaster.dk/domain/list/handle/{userid}/role/{role}` has been removed
- Support for user handles in domain query result sets have been removed (`registrant_userid`, `query_userid` and `userid`), for API endpoints: `https://whois-api.dk-hostmaster.dk/domain/{domainname}` and `https://whois-api.dk-hostmaster.dk/#query`

- 2.1 2019-11-19
- Updated section on rate limiting based on changes to production environment

Expand All @@ -102,7 +103,6 @@ The service implements the following features.

- Domain name inquiry
- Host name inquiry
- Handle inquiry
- Support for multiple encodings (see: [Encoding](#encoding) below)
- Support for both IPv4 and IPv6

Expand Down Expand Up @@ -154,7 +154,6 @@ The service offers four APIs, one specialized for each entity type:

- domain (domain name)
- host (hostname/name server)
- handle (userid)

And a generic API:

Expand All @@ -169,52 +168,75 @@ As described under Implementation Limitations, the service only supports **JSON*
If the header is unspecified, not specified correctly or specified to an unsupported format, the service will error with HTTP status code: `415`

```bash
$ curl https://whois-api.dk-hostmaster.dk/handle/DKHM1-DK
$ curl https://whois-api.dk-hostmaster.dk/domain/eksempel.dk
"Unsupported Media Type"
```

Correct specification using `curl` should be as follows:

```bash
$ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/handle/DKHM1-DK
{"attention":null,"city":"København S","countryregionid":"DK","message":"OK","mobilephone":null,"name":"DK HOSTMASTER A\/S","phone":null,"query_userid":"DKHM1-DK","status":200,"street1":"Ørestads Boulevard 108, 11.","street2":null,"street3":null,"telefax":null,"userid":"DKHM1-DK","useridtype":"V","validregistrant":"1","zipcode":"2300"}
$ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/domain/eksempel.dk
{"createddate":"1999\/05\/17","dnssec":"J","domain":"eksempel.dk","domain_encoded":"eksempel.dk","domain_type":"V","message":"OK","nameservers":{"auth01.ns.dk-hostmaster.dk":{"domain":"eksempel.dk","domain_encoded":"eksempel.dk","hostname":"auth01.ns.dk-hostmaster.dk","hostname_encoded":"auth01.ns.dk-hostmaster.dk"},"auth02.ns.dk-hostmaster.dk":{"domain":"eksempel.dk","domain_encoded":"eksempel.dk","hostname":"auth02.ns.dk-hostmaster.dk","hostname_encoded":"auth02.ns.dk-hostmaster.dk"}},"paiduntildate":"2022\/06\/30","periodqty":"5","public_deletedate":null,"public_domain_status":"A","registrant":{"attention":null,"city":"København S","countryregionid":"DK","mobilephone":null,"name":"DK HOSTMASTER A\/S","phone":null,"street1":"Ørestads Boulevard 108, 11.","street2":null,"street3":null,"telefax":null,"useridtype":"V","validregistrant":"1","zipcode":"2300"},"status":200}
```

And for `httpie`

```bash
$ http https://whois-api.dk-hostmaster.dk/handle/DKHM1-DK Accept:'application/json'
$ http https://whois-api.dk-hostmaster.dk/domain/eksempel.dk Accept:'application/json'

HTTP/1.1 200 OK
Cache-Control: max-age=1, no-cache
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Date: Mon, 22 Apr 2019 11:25:24 GMT
Date: Mon, 25 Nov 2019 09:29:41 GMT
Server: nginx
Strict-Transport-Security: max-age=15768000
Transfer-Encoding: chunked
Vary: Accept-Encoding
Vary: Origin

{
"attention": null,
"city": "København S",
"countryregionid": "DK",
"createddate": "1999/05/17",
"dnssec": "J",
"domain": "eksempel.dk",
"domain_encoded": "eksempel.dk",
"domain_type": "V",
"message": "OK",
"mobilephone": null,
"name": "DK HOSTMASTER A/S",
"phone": null,
"query_userid": "DKHM1-DK",
"status": 200,
"street1": "Ørestads Boulevard 108, 11.",
"street2": null,
"street3": null,
"telefax": null,
"userid": "DKHM1-DK",
"useridtype": "V",
"validregistrant": "1",
"zipcode": "2300"
"nameservers": {
"auth01.ns.dk-hostmaster.dk": {
"domain": "eksempel.dk",
"domain_encoded": "eksempel.dk",
"hostname": "auth01.ns.dk-hostmaster.dk",
"hostname_encoded": "auth01.ns.dk-hostmaster.dk"
},
"auth02.ns.dk-hostmaster.dk": {
"domain": "eksempel.dk",
"domain_encoded": "eksempel.dk",
"hostname": "auth02.ns.dk-hostmaster.dk",
"hostname_encoded": "auth02.ns.dk-hostmaster.dk"
}
},
"paiduntildate": "2022/06/30",
"periodqty": "5",
"public_deletedate": null,
"public_domain_status": "A",
"registrant": {
"attention": null,
"city": "København S",
"countryregionid": "DK",
"mobilephone": null,
"name": "DK HOSTMASTER A/S",
"phone": null,
"street1": "Ørestads Boulevard 108, 11.",
"street2": null,
"street3": null,
"telefax": null,
"useridtype": "V",
"validregistrant": "1",
"zipcode": "2300"
},
"status": 200
}
```

Expand All @@ -225,6 +247,8 @@ This service returns data on a given domain name.

As of version 2.X.X of the service, admin/proxy information is no longer part of the response data, same goes for name server administrators/zone contact handles.

As of version 3.X.X of the service, registrant user-id/handle information is no longer part of the response data.

<a id="api"></a>
### API

Expand Down Expand Up @@ -287,144 +311,18 @@ $ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/do
"mobilephone": null,
"name": "DK HOSTMASTER A/S",
"phone": null,
"query_userid": "DKHM1-DK",
"street1": "Ørestads Boulevard 108, 11.",
"street2": null,
"street3": null,
"telefax": null,
"userid": "DKHM1-DK",
"useridtype": "V",
"validregistrant": "1",
"zipcode": "2300"
},
"registrant_userid": "DKHM1-DK",
"status": 200
}
```

<a id="domain-list"></a>
## domain list

<a id="api-1"></a>
### API

`https://whois-api.dk-hostmaster.dk/domain/list/handle/{userid}/role/{role}`

The service returns `200` if it can find a relevant object holding the relevant role. Supported role types values is: `registrant` only.

As of version 2.X.X of the service, admin/proxy information is no longer supported.

<a id="example-1"></a>
### Example

Using `httpie`

```bash
$ http https://whois-api.dk-hostmaster.dk/domain/list/handle/DKHM1-DK/role/registrant Accept:'application/json'
```

Using `curl` and `jq`

```bash
$ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/domain/list/handle/DKHM1-DK/role/registrant | jq
```

```json
{
"attention": null,
"city": "København S",
"countryregionid": "DK",
"domains": [
{
"domain": "dk-hostmaster.dk",
"domain_encoded": "dk-hostmaster.dk"
},
{
"domain": "æøåöäüé.dk",
"domain_encoded": "xn--4cabco7dk5a.dk"
}
],
"message": "OK",
"mobilephone": null,
"name": "DK HOSTMASTER A/S",
"phone": null,
"query_userid": "DKHM1-DK",
"role": "registrant",
"status": 200,
"street1": "Ørestads Boulevard 108, 11.",
"street2": null,
"street3": null,
"telefax": null,
"userid": "DKHM1-DK",
"useridtype": "V",
"validregistrant": "1",
"zipcode": "2300"
}
```

| Return Code | Description |
| ------------ | ------------ |
| `200` | OK |
| `400` | Bad request |
| `404` | Object not found |
| `415` | Unsupported media type |

<a id="handle"></a>
## handle

This service returns data on a given handle/user-id. The service only returns data on active users with the `registrant` role.

As of version 2.X.X of the service, admin/proxy and name server administrator/zone contact information is no longer available via this service.

<a id="api-2"></a>
### API

`https://whois-api.dk-hostmaster.dk/handle/{userid}`

| Return Code | Description |
| ------------ | ------------ |
| `200` | OK |
| `400` | Bad request |
| `404` | Object not found |
| `415` | Unsupported media type |

<a id="example-2"></a>
### Example

Using `httpie`

```bash
$ http https://whois-api.dk-hostmaster.dk/handle/DKHM1-DK Accept:'application/json'
```

Using `curl` and `jq`

```bash
$ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/handle/DKHM1-DK | jq
```

```json
{
"attention": null,
"city": "København S",
"countryregionid": "DK",
"message": "OK",
"mobilephone": null,
"name": "DK HOSTMASTER A/S",
"phone": null,
"query_userid": "DKHM1-DK",
"status": 200,
"street1": "Ørestads Boulevard 108, 11.",
"street2": null,
"street3": null,
"telefax": null,
"userid": "DKHM1-DK",
"useridtype": "V",
"validregistrant": "1",
"zipcode": "2300"
}
```

<a id="host"></a>
## host

Expand Down Expand Up @@ -535,17 +433,14 @@ $ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/qu
"mobilephone": null,
"name": "DK HOSTMASTER A/S",
"phone": null,
"query_userid": "DKHM1-DK",
"street1": "Ørestads Boulevard 108, 11.",
"street2": null,
"street3": null,
"telefax": null,
"userid": "DKHM1-DK",
"useridtype": "V",
"validregistrant": "1",
"zipcode": "2300"
},
"registrant_userid": "DKHM1-DK",
"status": 200
}
```
Expand Down Expand Up @@ -576,43 +471,6 @@ $ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/qu
}
```

<a id="handle-example"></a>
### Handle Example

Using `httpie`

```bash
$ http https://whois-api.dk-hostmaster.dk/query/DKHM1-DK Accept:'application/json'
```

Using `curl` and `jq`

```bash
$ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/query/DKHM1-DK | jq
```

```json
{
"attention": null,
"city": "København S",
"countryregionid": "DK",
"message": "OK",
"mobilephone": null,
"name": "DK HOSTMASTER A/S",
"phone": null,
"query_userid": "DKHM1-DK",
"status": 200,
"street1": "Ørestads Boulevard 108, 11.",
"street2": null,
"street3": null,
"telefax": null,
"userid": "DKHM1-DK",
"useridtype": "V",
"validregistrant": "1",
"zipcode": "2300"
}
```

<a id="resources"></a>
# Resources

Expand Down

0 comments on commit f37c208

Please sign in to comment.