jwa.

Introduction

Our RESTful API provides a lightweight intuitive conduit to our services taking advantage of predictable, resource-oriented URLs and standard HTTP status codes. Server responses will make use of one of the designated HTTP codes listed further down this document. In addition, all data returned by our API will be JSON encoded and snake case is used for all field names to enhance readability.

If you have any quires, criticisms, suggestions or features requests we'd love to hear from you, drop us an email at david@jsonwhoisapi.com.


# These panels provide code and response object samples

Authentication

Being based on the HTTP protocol, our API is stateless. With every request you must send the [customer ID:API key] pair to authenticate - both pieces of information can be found when logged in to you account. These credentials must be passed via basic http authentication, this is made very easy by unirest as seen in the sample section to the right.
NB: When consuming our API without the use of the unirest libraries please remember that in basic HTTP authentication the authentication credentials are passed via a header and not via the URL. For example, this is the wrong approach to take, https://customer_id:api_key@jsonwhoisapi.com/api/v1/whois. Wikipedia does a good job of summarising the correct way to use basic HTTP authentication.


Request.auth({
  user: {customer_id},
  pass: {api_key}
});

Unirest.get(url, headers: {}, parameters: nil, auth:{:user=>{customer_id}, :password=>{api_key}}, &callback)

Unirest\Request::auth({customer_id}, {api_key});





  

curl -X POST -s --user '{customer_id}:{api_key}' \
    https://jsonwhoisapi.com/api/v1

Response Codes

We have tried to map as closely as possible our needs to the inherint meaning of each HTTP code. One of these codes will be returned by our server with every request.

CMD_PROCESSED
200 OK
Command has been processed A short plain text explanation of the status of the request.
CMD_UNKNOWN
400 Bad Request
Unknown command The URI you are requesting is not supported, re-examine the list of commands on this page such as /whois and pick a valid one.
CMD_INVALID
405 Method not allowed
Invalid request method You cannot perform that method to this resource - the base of your call is correct but you cannot perform your action (GET,POST,PUT,DELETE) to your specified URI, re-examine the portion of this page corresponding to your chosen command and rebuild your request URI.
CMD_MALFORMED
409 Conflict
Your request is missing some parameters this means you are missing some required fields in the call, leaving out optional parameters will not cause this error, re-examine the list of minimum parameters required and rebuild your request URI.
USR_UNAUTHORIZED
401 Unauthorized
Authentication failed Ensure you are sending your customer ID and API key with each request as laid out in the authentication section of this page.
JWA_ERROR
500 Internal Server Error
An internal error has occurred at JsonWHOISAPI Everything regarding the request is correct, however our servers cannot fulfil the request at this point in time.

WHOIS (parsed) GET

/whois

This end point enables access to our WHOIS record fetching and parsing service.

Request fields

identifier
required
String The domain name for which you wish to query parsed WHOIS data.

Response fields

name
Always present
String The unuqiue identifier i.e. the domain name.
created
Always present
String The date the domain was registered to the current owner.
changed
Always present
String The date the domain was last updated.
expires
Always present
String The date the current registeration peroid expires.
dnssec
Always present
String The status of DNSsec for the domain.
registered
Always present
Bool Provides an indication as to wether the domain is currently registered.
status
Always present
Array Contians various elements indicating the statuses of the domain in question.
nameservers
Always present
Array Contians the location of the nameservers for the domain.
contacts
Always present
Object Contains {Key}:{Array} pairs where each array holds the corresponding contact information for the key it is associated with (e.g. for the 'owner').
registrar
Always present
Object Contains information pertaining to the registra orginaisation of the domain name.

$headers = array("Accept" => "application/json");
$url = "https://jsonwhoisapi.com/api/v1/whois?identifier=google.com";

$response = Unirest\Request::get($url, $headers);





  


curl -X GET -s --user '{customer_id}:{api_key}' \
    https://jsonwhoisapi.com/api/v1/whois?identifier='google.com'
# JSON Response
{
   "name":"google.com",
   "created":"1997-09-15 03:00:00",
   "changed":"2015-06-12 13:38:52",
   "expires":"2020-09-14 00:00:00",
   "dnssec":"unsigned",
   "registered":true,
   "status":[
      "clientUpdateProhibited (https:\/\/www.icann.org\/epp#clientUpdateProhibited)",
      "clientTransferProhibited (https:\/\/www.icann.org\/epp#clientTransferProhibited)",
      "clientDeleteProhibited (https:\/\/www.icann.org\/epp#clientDeleteProhibited)",
      "serverUpdateProhibited (https:\/\/www.icann.org\/epp#serverUpdateProhibited)",
      "serverTransferProhibited (https:\/\/www.icann.org\/epp#serverTransferProhibited)",
      "serverDeleteProhibited (https:\/\/www.icann.org\/epp#serverDeleteProhibited)"
   ],
   "nameservers":[
      "ns3.google.com",
      "ns4.google.com",
      "ns1.google.com",
      "ns2.google.com"
   ],
   "contacts":{
      "owner":[
         {
            "handle":null,
            "type":null,
            "name":"Dns Admin",
            "organization":"Google Inc.",
            "email":"dns-admin@google.com",
            "address":"Please contact contact-admin@google.com, 1600 Amphitheatre Parkway",
            "zipcode":"94043",
            "city":"Mountain View",
            "state":"CA",
            "country":"US",
            "phone":"+1.6502530000",
            "fax":"+1.6506188571",
            "created":null,
            "changed":null
         }
      ],
      "admin":[
         {
            "handle":null,
            "type":null,
            "name":"DNS Admin",
            "organization":"Google Inc.",
            "email":"dns-admin@google.com",
            "address":"1600 Amphitheatre Parkway",
            "zipcode":"94043",
            "city":"Mountain View",
            "state":"CA",
            "country":"US",
            "phone":"+1.6506234000",
            "fax":"+1.6506188571",
            "created":null,
            "changed":null
         }
      ],
      "tech":[
         {
            "handle":null,
            "type":null,
            "name":"DNS Admin",
            "organization":"Google Inc.",
            "email":"dns-admin@google.com",
            "address":"2400 E. Bayshore Pkwy",
            "zipcode":"94043",
            "city":"Mountain View",
            "state":"CA",
            "country":"US",
            "phone":"+1.6503300100",
            "fax":"+1.6506181499",
            "created":null,
            "changed":null
         }
      ]
   },
   "registrar":{
      "id":"292",
      "name":"MarkMonitor, Inc.",
      "email":"abusecomplaints@markmonitor.com",
      "url":"http:\/\/www.markmonitor.com",
      "phone":"+1.2083895740"
   }
}
              
            

JSON WHOIS API Libraries

This section of the documentation is dedicated to the user-contributed libraries and wrapper classes created by the open source community for jwa.
All code offered in this section comes without any warranty, implied or otherwise.

Libraries and wrapper classes


Built your own library or created some useful code you'd like to share? Send us a link to your code and we'll be happy to add it to the list!








  



# Please refer to the respective documentation for each library