diff --git a/README.md b/README.md index 0631115..f9e8235 100644 --- a/README.md +++ b/README.md @@ -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 - + - [Introduction](#introduction) - [About this Document](#about-this-document) @@ -32,9 +32,6 @@ 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) @@ -42,7 +39,6 @@ Revision: 2.1 - [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) @@ -62,7 +58,7 @@ The WHOIS RESTful service is optimized for structured querying in contrast to it # 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. @@ -76,6 +72,11 @@ This document is copyright by DK Hostmaster A/S and is licensed under the MIT Li ## 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 @@ -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 @@ -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: @@ -169,28 +168,28 @@ 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 @@ -198,23 +197,46 @@ 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 } ``` @@ -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. + ### API @@ -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 } ``` - -## domain list - - -### 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. - - -### 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 | - - -## 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. - - -### 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 | - - -### 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" -} -``` - ## host @@ -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 } ``` @@ -576,43 +471,6 @@ $ curl --header "Accept: application/json" https://whois-api.dk-hostmaster.dk/qu } ``` - -### 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" -} -``` - # Resources