Skip to content

REST API

Jump to bottom Edit New page
rafaeljusto edited this page Sep 29, 2014 · 50 revisions

Welcome to the Shelter REST API. With this API you can create your own applications to integrate with Shelter system sending and checking domain objects. The objective is to make it easier for registries to verify your clients' domains configurations, once the client registry a domain, you can send it to the Shelter system, that will monitor the domain and alert about any problem.

As the domain data of a registry is an important information, the REST server should be inside the registry infrastructure. The idea is that the Shelter system will receive requests only from the registry's front-end or back-end servers. For that reason you will need to define in the REST configuration the ACL addresses that are authorized to interact with the REST API.

Table of Contents

Request domain object

Now let's talk about the main object that will be exchanged between you and the REST server, the domain object. To make it simpler we adopted JSON format. The domain object has only the necessary information to validate the DNS and DNSSEC basic configurations, and also some contact information to send alert e-mails for the domain owners. Let's take a look on it:

{
  "nameservers": [
    { "host": "ns1.example.com.br.", "ipv4": "192.0.2.1", "ipv6": "fc00::1" },
    { "host": "ns2.example.com.br.", "ipv4": "192.0.2.2", "ipv6": "fc00::2" },
    ...
  ],
  "dsset": [
    { "keytag": 1234, "algorithm": 5, "digest": "abcdefghij==", "digestType": 1},
    { "keytag": 1235, "algorithm": 8, "digest": "jihgfedcba==", "digestType": 2},
    ...
  ],
  "dnskeys": [
    { "flags": 257, "algorithm": 5, "publicKey": "AwEAAfFQjspE" },
    { "flags": 256, "algorithm": 8, "publicKey": "AwEAAblaEaap" },
    ...
  ],
  "owners": [
    { "email": "contact1@email.com.br.", "language": "pt-BR" },
    { "email": "contact2@email.com.br.", "language": "en-US" },
    ...
  ]
}

FQDN

You are probably asking, and where do you tell the FQDN of this domain?!? Easy. This will be informed in the URI. For example, to create a domain object, the URI will be /domain/example.com.br, so there's no need to repeat this information inside the object body.

Nameservers

You can inform how many nameservers you want, they are all going to be checked. The nameserver's host can be informed with or without an end dot in the name (the system will add one if necessary). When the nameserver's host needs glue records you should also inform the ipv4 or ipv6 address. All the information are validated, and if something is wrong you will receive an HTTP Bad Request status with the error description in the body of the response. We will talk later about the error response format.

DS set

The DS set is optional and you inform this only if you want that the Shelter system verify the DNSSEC configuration of the domain. You can inform how many DS records that you want, they will be all checked. The keytag value, as described on RFC 4034 - Section 5.1.1 should be the DNSKEY identification stored in the client's zone. The algorithm field can have the values described in the Algorithm Numbers. The digest is the hash of the DNSKEY. And the digest type can have the values also described in the DS Digest Algorithms. Please alert me if there's any value from the references above that is not supported by the Shelter system.

DNSKEY

To make it easier for the registry, the Shelter system can also store DS records from client's DNSKEY. You can inform how many DNSKEYs entries that you want, they will be all converted to DS entries in the domain object before stored in the Shelter system. The flags field is a group of bits that are described in the DNSKEY Flags, as we are talking about DNSSEC, you should probably always use the ZONE bit, and maybe use the REVOKE and SEP bits, so the possible values that you should use are:

Number Flags
256 ZONE
257 ZONE+SEP
768 ZONE+Revoke
769 ZONE+SEP+Revoke

The algorithm field is the same as for the DS related, you can check the possible values in the Algorithm Numbers. And the publicKey field that is the DNSKEY content itself. The conversion to a DS record will be always used the digest type SHA-256.

Owners

The last group of the domain object is a list of pairs of e-mails and languages that will be used to to alert the domain' owner everytime that we found any configuration problem in the domain using the owner's desired language. The language must be a valid language from IANA language subtag registry. For more information of how to configure the alert messages please check the section Install and Configure.

Response domain object

The Shelter system also sends back a domain object for you, but the format is slight different from the one you sent to the server. Let's take a look:

{
  "fqdn": "example.com.br.",
  "nameservers": [
    {
      "host": "ns1.example.com.br.", 
      "ipv4": "192.0.2.1", 
      "ipv6": "fc00::1",
      "lastStatus": "OK",
      "lastCheckAt": "2014-01-22T15:41:57Z-3:00",
      "lastOKAt": "2014-01-22T15:41:57Z-3:00"
    },
    {
      "host": "ns2.example.com.br.",
      "ipv4": "192.0.2.2",
      "ipv6": "fc00::2",
      "lastStatus": "NOAA",
      "lastCheckAt": "2014-01-22T15:41:57Z-3:00",
      "lastOKAt": "2014-01-20T10:28:08Z-3:00"
    },
    ...
  ],
  "dsset": [
    {
      "keytag": 1234, 
      "algorithm": 5, 
      "digest": "abcdefghij==", 
      "digestType": 1,
      "expiresAt": "2014-04-22T12:00:00Z-3:00",
      "lastStatus": "DNSERR",
      "lastCheckAt": "2014-01-22T15:41:57Z-3:00",
      "lastOKAt": "2014-01-20T10:28:08Z-3:00"
    },
    {
      "keytag": 1235, 
      "algorithm": 8, 
      "digest": "jihgfedcba==", 
      "digestType": 2,
      "expiresAt": "2014-06-01T12:00:00Z-3:00",
      "lastStatus": "DNSERR",
      "lastCheckAt": "2014-01-22T15:41:57Z-3:00",
      "lastOKAt": "2014-01-20T10:28:08Z-3:00"
    },
    ...
  ],
  "owners": [
    { "email": "contact1@email.com.br.", "language": "pt-BR" },
    { "email": "contact2@email.com.br.", "language": "en-US" },
    ...
  ],
  "links": [
    { "types": [ "self" ], "href": "/domain/example.com.br." },
    ...
  ]
}

FQDN

In the response now we have the FQDN inside the object data, the reason for that is to identify witch FQDN you are managing when you receive a list of domain objects.

Nameservers

Now for each nameserver we have some extra information sent in the response that identifies the current configuration state of the host from the scans results. The lastStatus field represents the status of the nameserver on the last scan, the possible values of this field are:

Status Description
NOTCHECKED Nameserver not checked yet
OK DNS configuration for this nameserver is OK
TIMEOUT Network timeout while trying to reach the nameserver
NOAA Nameserver has no authority over the domain
UDN Domain does not exists for this nameserver
UH Could not resolve nameserver's name (no glue)
SERVFAIL Nameserver zone configuration problem, check log file of the nameserver
QREFUSED DNS request was rejected by the nameserver
CREFUSED Connection was refused by firewall or nameserver
CNAME Domain name is a link in the zone APEX
NOTSYNCH Nameservers of this domain have a different version of the zone files
ERROR Generic error found in the nameserver

The known the date that the lastStatus was applied you can check the lastCheckAt field. This fields represents the last time that this domain was scanned. The scan systems runs periodically, but the domain will not be selected to be scanned on every scan (for more details check the Scan section in the Project Design page).

You also probably want to known when was the last time that a domain was well configured, so the field lastOKAt will be responsible for that. The dates found in the nameserver will also be used by the Shelter system to alert domain's owners about configuration problems.

DSSet

For each DS record we will also add some extra information on the response. To alert about DNSSEC signatures expiration, the Shelter system stores, on every scan, the expiration of the signature related to the DS record (DNSKEY) in the field expiresAt. This field will be used to send alerts to domain's owners in order to make them resign the zone before the signatures expires.

In the same way of the nameserver, the DS record also have an status, that is stored in the lastStatus field, that represents the state in the last time that was scanned. A list of the possible values of this field is described bellow.

Status Description
NOTCHECKED DS record not checked yet
OK DNSSEC configuration for this DS is OK
TIMEOUT Network timeout while trying to retrieve the DNSKEY
NOSIG No RRSIG records found for the related DNSKEY
EXPSIG At least one RRSIG record was expired
NOKEY No DNSKEY was found with the keytag of the DS
NOSEP DNSKEY related to DS does not have the bit SEP on
SIGERR Error while checking DNSKEY signatures
DNSERR DNS error (check nameserver status)

The Shelter system also stores the last time that the domain was configured correctly with DNSSEC for the give DS record. This date can be found in the field lastOKAt, and is used for alerting domain's owners about DNSSEC problems.

You are not going to see DNSKEYs in the response, because they were all converted into DS records during the create or update commands.

Links

Each domain object can be linked to other resources, so in the response you will also receive a list of links for each domain. A link is represented by the field types that stores all possible types that point for the same URL, and by the field href that stores the URL. The possible types of a link can be found in the IANA link relations XML.

This links are really useful when you receive a list of domains and want to retrieve information from one of them. Using links will guarantee that your client application will always use the last APIs.

Response scan object

The scan object stores the result information from a executed scan or the details from a scan that is running or is going to run. It stores statistics information and necessary data to identify the scan progress. The scan object has the following structure:

{
  "status": "EXECUTED",
  "scheduledAt": "0001-01-01T00:00:00Z",
  "startedAt": "2014-02-10T13:38:01.1234-02:00",
  "finishedAt": "2014-02-10T14:12:58.7890-02:00",
  "domainsToBeScanned": 0,
  "domainsScanned": 3375423,
  "domainsWithDNSSECScanned": 753976,
  "nameserverStatistics": {
    "OK": 3275423,
    "TIMEOUT": 100000
  },
  "dsStatistics": {
    "OK": 653976,
    "EXPSIG": 100000
  },
  "links": {
    "types": [ "self" ],
    "href": "/scan/2014-02-10T13:38:01.1234-02:00"
  }
}

Status

Text field created to store the current status of the scan. Possible values are listed bellow.

Status Description
WAITINGEXECUTION Scan did not started yet
LOADINGDATA Loading domains that are going to be scanned
RUNNING Checking domains
EXECUTED Scan finished
EXECUTEDWITHERRORS Scan finished with errors, check the log file

ScheduledAt

Date and time that the scan will be probably executed, probably because the scheduler doesn't run always at the moment that the scan job should run. This field should be analyzed only if you are checking the current scan, otherwise you should check startedAt to determinate the real start date. The format of this date and time field follows the RFC 3339 with milliseconds.

StartedAt

Date and time that the scan started. The format of this date and time field follows the RFC 3339 with milliseconds. When retrieving a scan, the startedAt field with milliseconds is used to identify it.

FinishedAt

Date and time that the scan finished their job. The format of this date and time field follows the RFC 3339 with milliseconds. When analyzing the current scan this field should not be verified.

DomainsToBeScanned

Number of domains loaded and ready to be scanned. This field is great while the scan is being executed, so you can estimate the progress of the scan and foresee a finish time. For the other scans this field should be ignored.

DomainsScanned

Number of domains already scanned. As with the field domainsToBeScanned, this field can be used to detect the progress of the scan, and later generate reports about the number of domains scanned.

DomainsWithDNSSECScanned

Number of domains that had DS records and were verified by the DNSSEC policies. This field can be used for reports to generate statistics.

NameserverStatistics

Count the number of occurrences of a specific nameserver status during the scan execution. This data is only available after the scan is executed. The possible status are described in the section Response domain object - Nameservers.

DSStatistics

Count the number of occurrences of a specific DS status during the scan execution. This data is only available after the scan is executed. The possible status are described in the section Response domain object - DSSet.

Links

Each scan object can be linked to other resources, so in the response you will also receive a list of links for each scan. A link is represented by the field types that stores all possible types that point for the same URL, and by the field href that stores the URL. The possible types of a link can be found in the IANA link relations XML.

Response message object

When something goes wrong because of the request data, or the server wants to send you a message, you will receive the message object as response. Let's have a look:

{
  "id": "accept-error",
  "message": "Shelter REST server can only return messages in application/vnd.shelter+json format",
  "links": [
    { "types": [ "related" ], "href": "/domain/example.com.br." },
    ...
  ]
}

Id and Message

An easy way to program your system to do something when receive an specific error. Bellow you will find each possible id that can be returned with the related message. The message can be translated to other languages according to the Accept-Language HTTP header field sent in the request.

id message
accept-error Shelter REST server can only return messages in application/vnd.shelter+json format
accept-charset-error Shelter REST server can only return messages in UTF-8 charset
accept-language-error Shelter REST server don't support the desired language
invalid-uri URI has an invalid format
date-missing HTTP header Date missing
invalid-header-date One ore more dates in HTTP header have an invalid format
content-type-missing HTTP header Content-Type missing
invalid-content-type Content Type not supported
content-md5-missing HTTP header Content-MD5 missing
invalid-content-md5 Content MD5 hash doesn't match with HTTP header
invalid-json-content JSON content has an invalid format
invalid-date-time-frame Date in HTTP header is outside the time frame
authorization-missing HTTP header Authorization missing
invalid-authorization HTTP header Authorization has an invalid format
secret-not-found HTTP header Authorization has an unknown secret id
invalid-if-match If-Match HTTP header should be a number related to an entity version
invalid-if-none-match If-None-Match HTTP header should be a number related to an entity version
if-match-failed Object has a different ETag from the ETags defined in the If-Match HTTP header field
if-none-match-failed Object has one of the ETags defined in the If-None-Match HTTP header field
conflict Object was already modified since your object's version, please update the object using the last version of it
invalid-query-order-by Query string has an invalid order-by filter
invalid-query-page-size Query string has an invalid page size filter. It must be a number
invalid-query-page Query string has an invalid current page filter. It must be a number

Links

As described in the domain object the links attribute are used to associate, in this case a message to a object of the system (that will be probably a domain). A link is represented by the field types that stores all possible types that point for the same URL, and by the field href that stores the URL. The possible types of a link can be found in the IANA link relations XML.

Request HTTP headers

There're some HTTP headers that you will need to send on every request, others HTTP headers are optional. The reason is that we use the HTTP headers for security verifications, and optionally to allow caching strategies. We will explain each one bellow.

Method

Method HTTP header tells the Shleter system what action do you want in the given URI. The allowed methods are described on each URI description in the examples sections bellow in this document. For more information check the RFC 2616 - 9.

Date

To avoid replay attacks and as a part of the authorization data, the Date HTTP header is mandatory and must be always the current time, using the RFC 1123 format. For more details check the RFC 2616 - 14.18.

Content-Type

The content type defines the format of the data. For now the Shelter system only supports application/vnd.shelter+json. To retrieve the supported content types of the server, you can always send a request with the method HEAD and check the Accept HTTTP header on the response. In the content type you also define the content charset as an option. For example, if your content is utf-8 the content type could be application/vnd.shelter+json;charset=utf-8. When there's no charset option the system will use utf-8. For more details check the RFC 2616 - 14.17.

Content-Length

Specify the size of the data. For more details check the RFC 2616 - 14.13.

Content-MD5

Guarantee the data integrity creating a MD5 hash of it and encoding to base64. This is also used as a authorization data to validate the user access and is mandatory when there's a message body. For more details check the RFC 2616 - 14.15.

Authorization

The Authorization HTTP header is used to close the API only for specific users. The authorization works in the same way of the Amazon REST API. Basically the Authorization HTTP header field is a data signed with a secret (symmetric key) that is known by the client and by the server. The data is a group of information (most part from the HTTP headers) listed bellow.

dataToSign = HTTP-Method + "\n" +
  HTTP-Content-MD5 + "\n" +
  HTTP-Content-Type + "\n" +
  HTTP-Date + "\n" +
  AccessKeyID + "\n" +
  URI + "\n" +
  CanonicalizedQueryString

Where:

  • AccessKeyID is an identifier number that is related to the secret on the server (that way the server can use the same key that you did)
  • URI is the path to the service. For example if the service URL is https://myregistry.com.br/domain/example.com.br. the URI should be only /domain/example.com.br.
  • All parameters sent via query string should also be a part of the data to be encrypted, and they must be ordered in alphabetical order. For example the URL https://myregistry.com.br/domains/?pagesize=10&page=1&orderby=fqdn:desc the CanonicalizedQueryString should be orderby=fqdn:desc&page=1&pagesize=10

The final format of the Authorzation HTTP header should be:

Authorization: shelter <AccessKeyID>:<SignedData>

More examples of Authorization HTTP headers can be found on the bellow sections. For more details check the RFC 2616 - 14.8.

Accept

You can specify the data formats that you support. The Shelter system will pick one of the to send back the data. For now the only supported format is appplication/vnd.shelter+json. This is an optional header, when is not informed, we assume that you support everything. For more details check the RFC 2616 - 14.1.

Accept-Charset

In the same way that you can tell the data format that you desire, you can also tell the charset that you support. For now the Shelter system can only send responses in UTF-8. This is an optional header, when is not informed, we assume that you support all charsets. For more details check the RFC 2616 - 14.2.

Accept-Language

Shelter system can return many messages for you to alert about errors or reports. You can specify the language that you want for this messages. To see the languages that the Shelter system support, send a request with the HEAD HTTP method and check the Accept-Language HTTP header of the response. This is an optional field, if not informed the system will choose a default language to send back the message. For more details check the RFC 2616 - 14.4.

If-Modified-Since

This is useful for caching the data. You add a condition to perform the action only if the data associated with the URI had changed since the date you send in the If-Modified-Since HTTP header. Useful when retrieving an object to avoid spending bytes over the network when not necessary. This header is optional. For more details check the RFC 2616 - 14.25.

If-Unmodified-Since

This is useful for caching the data. You add a condition to perform the action only if the data associated with the URI had not changed since the date you send in the If-Unmodified-Since HTTP header. Useful when removing an object to guarantee that no one updated the object after the version that you are trying to remote. This header is optional. For more details check the RFC 2616 - 14.28.

If-Match

All objects in the system have versions, you can store this versions (sent in ETag HTTP responses) and use them as conditions for the requests. This is very useful for concurrent transactions. The If-Match HTTP header only perform the action if the current object version is the same as defined on this HTTP header. This header is optional. For more details check the RFC 2616 - 14.24.

If-None-Match

The If-None-Match HTTP header is the opposite of the If-Match HTTP header. Only perform the action if the current object version don't match with the version defined on this HTTP header. This header is optional. For more details check the RFC 2616 - 14.26.

Response HTTP headers

The REST server also send some HTTP headers in the response that describes what the systems supports. Bellow you will find a description of each HTTP response header.

Accept

Return all formats that the REST server supports. For now is only application/vnd.shelter+json. This header will be sent on every response. For more details check the RFC 2616 - 14.1.

Accept-Language

Return all supported languages of the system. This header will be sent on every response. For more details check the RFC 2616 - 14.4.

Accept-Charset

Return the supported charsets of the REST server. For now we only supports utf-8, if you use another charset (like iso-8859-1) you should convert it before sending it to the REST server. This header will be sent on every response. For more details check the RFC 2616 - 14.2.

Content-Type

The content type defines the format of the data. For now the Shelter system only supports application/vnd.shelter+json. This header will be sent on every response, even if there's no content (check Content-Length to known if there's data or not). For more details check the RFC 2616 - 14.17.

Content-Language

REST server can return many messages due to errors, this HTTP header will tell you in which language these messages are. You can also change the language used by the REST server, sending in the request the "Accept-Language" header. It will be sent on every response. For more details check the RFC 2616 - 14.12.

Content-Length

Inform the data size. The REST server always sent this header in the response. For more details check the RFC 2616 - 14.13.

Content-MD5

Guarantee the data integrity creating a MD5 hash of it and encoding to base64. This header will be sent in the response only if there's some content. For more details check the RFC 2616 - 14.15.

Date

Date used only as a reference of the time that the request was executed on the server, it will be in the RFC 1123 format. This header will be sent on every response. For more details check the RFC 2616 - 14.18.

ETag

Represents the object version, that in the Shelter system, is an incremental number. You can use it to control object updates concurrency and caching. This header will be sent on the response every-time you retrieve or update a single object. For more details check the RFC 2616 - 14.19.

Last-Modified

Represents the date that the object was last modified. You can use it to control object updates concurrency and caching. As the ETag header field this header will also be sent on the response every-time you retrieve or update a single object. It uses the RFC 1123 format. For more details check the RFC 2616 - 14.29.

Location

Returns the URI of the newly created object, and make it easy to automate your client. This HTTP header is sent only on the object creation. For more details check the RFC 2616 - 14.30.

URIs

The REST API allows creating, updating and deleting a domain from the Shelter system. Bellow you will find the supported URIs. All examples were generated using a Go test program that can be found here.

/domain/{FQDN}

Create domain (PUT)

Request

Example:

PUT /domain/example.com.br. HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:NPDjJsNtvPcCcUrAzdD1NNvfvj4=
Content-Length: 384
Content-Md5: KbKz608cFomq5zbyR4pu0g==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:16:37 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http
{
 "nameservers": [
  {
   "host": "ns1.example.com.br.",
   "ipv4": "192.0.2.1",
   "ipv6": "fc00::1"
  },
  {
   "host": "ns2.example.com.br.",
   "ipv4": "192.0.2.2",
   "ipv6": "fc00::2"
  }
 ],
 "dsset": [
  {
   "keytag": 48681,
   "algorithm": 7,
   "digest": "42CD908170D80FCD5B42F83A43166EE348785263",
   "digestType": 1
  }
 ]
}

Response

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
201 (Created) Success HTTP status code
304 (Not Modified) When the condition of "If-Modified-Since" HTTP header is not satisfied
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
409 (Conflict) Concurrency problem while saving the object
412 (Precondition Failed) When the condition of "If-Unmodified-Since", "If-Match" or "If-None-Match" HTTP headers are not satisfied
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 201 Created
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:16:37 UTC
Etag: 1
Last-Modified: Tue, 03 Jun 2014 17:16:37 UTC
Location: /domain/example.com.br.

Update domain (PUT)

This action will overwrite the object persisted on the Shelter system. If you don't send a part of the object, for example the DS set, the Shelter system will understand that the DS set stored should be removed.

Request

Example:

PUT /domain/example.com.br. HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:d/+QXxgjN9qUR30hVpI2zCgDgAw=
Content-Length: 227
Content-Md5: ua5sEOAEHK0AyTEWUQJyCg==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:16:37 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http
{
 "nameservers": [
  {
   "host": "ns3.example.com.br.",
   "ipv4": "192.0.2.3",
   "ipv6": "fc00::3"
  },
  {
   "host": "ns4.example.com.br.",
   "ipv4": "192.0.2.4",
   "ipv6": "fc00::4"
  }
 ]
}

Response

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
204 (No Content) Success HTTP status code
304 (Not Modified) When the condition of "If-Modified-Since" HTTP header is not satisfied
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
409 (Conflict) Concurrency problem while saving the object
412 (Precondition Failed) When the condition of "If-Unmodified-Since", "If-Match" or "If-None-Match" HTTP headers are not satisfied
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 204 No Content
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:16:37 UTC
Etag: 2
Last-Modified: Tue, 03 Jun 2014 17:16:37 UTC

Retrieve domain (GET)

Request

Example:

GET /domain/example.com.br. HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:1AZDdhaooDc7yQsX756803ezO4w=
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:16:37 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http

Response

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
200 (OK) Success HTTP status code
304 (Not Modified) When the condition of "If-Modified-Since" or "If-None-Match" HTTP headers are not satisfied
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
404 (Not Found) Domain object not found in the Shelter system
412 (Precondition Failed) When the condition of "If-Unmodified-Since" or "If-Match" HTTP headers are not satisfied
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 200 OK
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 432
Content-Md5: rBwJtXF/GIWrk4IbZS3N4A==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:16:37 UTC
Etag: 2
Last-Modified: Tue, 03 Jun 2014 14:16:37 BRT
{
 "fqdn": "example.com.br.",
 "nameservers": [
  {
   "host": "ns3.example.com.br.",
   "ipv4": "192.0.2.3",
   "ipv6": "fc00::3",
   "lastStatus": "NOTCHECKED",
   "lastCheckAt": "0001-01-01T00:00:00Z",
   "lastOKAt": "0001-01-01T00:00:00Z"
  },
  {
   "host": "ns4.example.com.br.",
   "ipv4": "192.0.2.4",
   "ipv6": "fc00::4",
   "lastStatus": "NOTCHECKED",
   "lastCheckAt": "0001-01-01T00:00:00Z",
   "lastOKAt": "0001-01-01T00:00:00Z"
  }
 ],
 "links": [
  {
   "types": [
    "self"
   ],
   "href": "/domain/example.com.br."
  }
 ]
}

Retrieve domain metadata (HEAD)

Request

Example:

HEAD /domain/example.com.br. HTTP/1.1
Accept-Charset: utf-8
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:rMr3PJ1Xz2fYZCGneVsQ4CfC3qc=
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:16:37 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http

Response

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
200 (OK) Success HTTP status code
304 (Not Modified) When the condition of "If-Modified-Since" or "If-None-Match" HTTP headers are not satisfied
400 (Bad Request) Something wrong with the input data
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
404 (Not Found) Domain object not found in the Shelter system
412 (Precondition Failed) When the condition of "If-Unmodified-Since" or "If-Match" HTTP headers are not satisfied
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example

HTTP/1.1 200 OK
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 432
Content-Md5: rBwJtXF/GIWrk4IbZS3N4A==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:16:37 UTC
Etag: 2
Last-Modified: Tue, 03 Jun 2014 14:16:37 BRT

Remove domain (DELETE)

Request

Example:

DELETE /domain/example.com.br. HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:xZO2Ow/mOcyhTK0vnjwjPepDmdo=
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:16:37 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http

Response

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
204 (No Content) Success HTTP status code
304 (Not Modified) When the condition of "If-Modified-Since" HTTP header is not satisfied
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
404 (Not Found) Domain object not found in the Shelter system
412 (Precondition Failed) When the condition of "If-Unmodified-Since", "If-Match" or "If-None-Match" HTTP headers are not satisfied
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 204 No Content
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:16:37 UTC

/domain/{FQDN}/verification

Scan domain (PUT)

This service should be used to verify if a domain is well configured with DNS/DNSSEC on the given nameservers. The domain verification is done synchronously and will return the results on-the-fly. The domain will not be registered in the system database. This should be useful for domain registration forms, to validate the user's inputs before start delegating the domain.

Request

This service doesn't support caching HTTP headers for now (If-Modified-Since, If-Unmodified-Since, If-Match or If-None-Match).

Example:

PUT /domain/br./verification HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:mE3eGfLXp/MmuZgiqpNkt2a19J8=
Content-Length: 195
Content-Md5: Cdjnv/b0Re8VYJZ3Qbb0pA==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:16:37 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http
{
 "nameservers": [
  {
   "host": "a.dns.br.",
   "ipv4": "200.160.0.10",
   "ipv6": "2001:12ff::10"
  },
  {
   "host": "b.dns.br.",
   "ipv4": "200.189.41.10"
  }
 ]
}

Response

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
200 (OK) Success HTTP status code
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 200 OK
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 0
Content-Md5: qzMq3pmrPklL24rNjR4lpg==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:16:37 UTC
{
 "fqdn": "br.",
 "nameservers": [
  {
   "host": "a.dns.br.",
   "ipv4": "200.160.0.10",
   "ipv6": "2001:12ff::10",
   "lastStatus": "OK",
   "lastCheckAt": "2014-06-03T14:16:37.825645856-03:00",
   "lastOKAt": "2014-06-03T14:16:37.825645856-03:00"
  },
  {
   "host": "b.dns.br.",
   "ipv4": "200.189.41.10",
   "lastStatus": "OK",
   "lastCheckAt": "2014-06-03T14:16:37.843385004-03:00",
   "lastOKAt": "2014-06-03T14:16:37.843385004-03:00"
  }
 ]
}

Query domain (GET)

This service should be used to retrieve a delegated domain information. The domain will not be registered in the system database.

Request

This service doesn't support caching HTTP headers for now (If-Modified-Since, If-Unmodified-Since, If-Match or If-None-Match).

Example:

GET /domain/rafael.net.br./verification HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:ALXxQEHvIkn2ZrKHxN73Aj6lvkI=
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:16:37 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http

Response

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
200 (OK) Success HTTP status code
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 200 OK
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 549
Content-Md5: BB1Sw2lm0Xv9bCo6eH9R2g==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:16:38 UTC
{
 "fqdn": "rafael.net.br.",
 "nameservers": [
  {
   "host": "a.sec.dns.br.",
   "lastStatus": "NOTCHECKED",
   "lastCheckAt": "0001-01-01T00:00:00Z",
   "lastOKAt": "0001-01-01T00:00:00Z"
  },
  {
   "host": "b.sec.dns.br.",
   "lastStatus": "NOTCHECKED",
   "lastCheckAt": "0001-01-01T00:00:00Z",
   "lastOKAt": "0001-01-01T00:00:00Z"
  }
 ],
 "dsset": [
  {
   "keytag": 26938,
   "algorithm": 5,
   "digest": "3e3c2996ed9b5a104639449bf1ef87b2c835b0800d5f1ebb04f5bf40391fd008",
   "digestType": 2,
   "expiresAt": "0001-01-01T00:00:00Z",
   "lastStatus": "NOTCHECKED",
   "lastCheckAt": "0001-01-01T00:00:00Z",
   "lastOKAt": "0001-01-01T00:00:00Z"
  }
 ]
}

/domains

Retrieve domains (GET)

Retrieve the list of domains stored in the Shelter system could be a problem when we are talking about more than 1 million domains. For that reason this service allows filters to create a pagination of the result set. The possible filter values are:

  • pagesize: Number of items that are going to be shown in one page
  • page: Defines the current page that you want to show
  • orderby: Order by a specific field and define the direction of the sort. The format used must be <field1>:<direction1>@<field2>:<direction2>@...@<fieldN>:<directionN>, where field can be for now fqdn or lastmodified, and the direction can be asc for ascending or desc for descending
  • expand: This flag indicates that the full domain object is desired in the returned list, otherwise only some basic information is returned
  • filter: Filter domains' result by the FQDN

For example, if I want to show the second page of the result set with 20 items per page, ordering by FQDN in descending direction and with the full domain object, it will be:

/domains?expand&pagesize=20&page=2&orderby=fqdn:desc

When no filter is given, the system will define default values for the pagination. In any case the system will return all the result set automatically, but you can set a page size bigger enough to return in only one page (at your own risk).

Request

Example:

GET /domains HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:6pCZEjkUeiJj6yqwaFXC+/HR7dI=
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:30:44 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http

Response

In the response, with the list of domain objects, you will also receive some information about the pagination used for the returned result set. Beyond the filters we described above, the server will return the numberOfPages, that was calculated using the total number of items divided by the page size, and the numberOfItems that is the number of domains in the result set. You will also see in the end of the response links to make it easy to navigate automatically on the pagination.

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
200 (OK) Success HTTP status code
304 (Not Modified) When the condition of "If-Modified-Since" or "If-None-Match" HTTP headers are not satisfied
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
412 (Precondition Failed) When the condition of "If-Unmodified-Since" or "If-Match" HTTP headers are not satisfied
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 200 OK
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 695
Content-Md5: S1XI63lqsjX9jbti/b1F9Q==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:30:44 UTC
Etag: 4b55c8eb796ab235fd8dbb62fdbd45f5
Last-Modified: Tue, 03 Jun 2014 14:30:44 BRT
{
 "page": 1,
 "pageSize": 20,
 "numberOfPages": 1,
 "numberOfItems": 2,
 "domains": [
  {
   "fqdn": "example1.com.br.",
   "nameservers": [
    {
     "lastStatus": "NOTCHECKED",
     "lastCheckAt": "0001-01-01T00:00:00Z",
     "lastOKAt": "0001-01-01T00:00:00Z"
    },
    {
     "lastStatus": "NOTCHECKED",
     "lastCheckAt": "0001-01-01T00:00:00Z",
     "lastOKAt": "0001-01-01T00:00:00Z"
    }
   ],
   "links": [
    {
     "types": [
      "self"
     ],
     "href": "/domain/example1.com.br."
    }
   ]
  },
  {
   "fqdn": "example2.com.br.",
   "nameservers": [
    {
     "lastStatus": "NOTCHECKED",
     "lastCheckAt": "0001-01-01T00:00:00Z",
     "lastOKAt": "0001-01-01T00:00:00Z"
    },
    {
     "lastStatus": "NOTCHECKED",
     "lastCheckAt": "0001-01-01T00:00:00Z",
     "lastOKAt": "0001-01-01T00:00:00Z"
    }
   ],
   "links": [
    {
     "types": [
      "self"
     ],
     "href": "/domain/example2.com.br."
    }
   ]
  }
 ]
}

/scan/current

Retrieve current scan (GET)

Deprecated. Since version 0.3 to retrieve the current scan you should use /scans/?current.

/scan/{started-at}

Retrieve scan (GET)

Request

Example

GET /scan/2014-06-03T14:31:34.878-03:00 HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:VRVu5f0WlPWmOLsXcduIBxaFVqQ=
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:32:44 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http

Response

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
200 (OK) Success HTTP status code
304 (Not Modified) When the condition of "If-Modified-Since" or "If-None-Match" HTTP headers are not satisfied
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
404 (Not Found) Scan object not found in the Shelter system
412 (Precondition Failed) When the condition of "If-Unmodified-Since" or "If-Match" HTTP headers are not satisfied
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 200 OK
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 277
Content-Md5: h70ZdTEvexRkIAsnYKjwSg==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:32:44 UTC
Etag: 1
Last-Modified: Tue, 03 Jun 2014 14:31:40 BRT
{
 "status": "EXECUTED",
 "scheduledAt": "0001-01-01T00:00:00Z",
 "startedAt": "2014-06-03T14:31:34.878-03:00",
 "finishedAt": "2014-06-03T14:31:40.884-03:00",
 "domainsScanned": 2,
 "nameserverStatistics": {
  "TIMEOUT": 4
 },
 "links": [
  {
   "types": [
    "self"
   ],
   "href": "/scan/2014-06-03T14:31:34.878-03:00"
  }
 ]
}

/scans

Retrieve scans (GET)

Request

Retrieve the list of scans stored in the Shelter system could be a problem over the time, because the number of scans will always increase. For that reason this service allows filters to create a pagination of the result set. The possible filter values are:

  • pagesize: Number of items that are going to be shown in one page
  • page: Defines the current page that you want to show
  • orderby: Order by a specific field and define the direction of the sort. The format used must be <field1>:<direction1>@<field2>:<direction2>@...@<fieldN>:<directionN>, where field can be for now startedat, domainsscanned or domainswithdnssecscanned, and the direction can be asc for ascending or desc for descending
  • expand: This flag indicates that the full scan object is desired in the returned list, otherwise only some basic information is returned
  • current: This flag indicates that the current scan (on execution or to be executed) should be returned

For example, if I want to show the second page of the result set with 20 items per page, ordering by the number of domains with DNSSEC in descending direction and with the full scan object, it will be:

/scans?expand&pagesize=20&page=2&orderby=domainswithdnssecscanned:desc

When no filter is given, the system will define default values for the pagination. In any case the system will return all the result set automatically, but you can set a page size bigger enough to return in only one page (at your own risk).

Example:

GET /scans/ HTTP/1.1
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-us
Accept: application/vnd.shelter+json
Authorization: shelter key01:70GSK0HJTH4/YlbAsPapsc/rF34=
Content-Length: 0
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 14:32:44 BRT
Host: localhost:4443
User-Agent: Go 1.1 package http

Response

In the response, with the list of scan objects, you will also receive some information about the pagination used for the returned result set. Beyond the filters we described above, the server will return the numberOfPages, that was calculated using the total number of items divided by the page size, and the numberOfItems that is the number of scans in the result set. You will also see in the end of the response links to make it easy to navigate automatically on the pagination.

REST server can return for this service one of the HTTP status listed bellow.

HTTP Status Description
200 (OK) Success HTTP status code
304 (Not Modified) When the condition of "If-Modified-Since" or "If-None-Match" HTTP headers are not satisfied
400 (Bad Request) Something wrong with the input data, check the message in the body for more details
403 (Forbidden) You are not allowed to access this server. Check the IP whitelist
412 (Precondition Failed) When the condition of "If-Unmodified-Since" or "If-Match" HTTP headers are not satisfied
500 (Internal Server Error) Something went wrong in the server. If the error persists check the server log file

Example:

HTTP/1.1 200 OK
Accept-Charset: utf-8
Accept-Encoding: gzip
Accept-Language: en-US,pt-BR,es-ES
Accept: application/vnd.shelter+json
Content-Language: en-US
Content-Length: 346
Content-Md5: 5vCHW7bgyW22Fy2KOI1qAA==
Content-Type: application/vnd.shelter+json; charset=utf-8
Date: Tue, 03 Jun 2014 17:32:44 UTC
Etag: e6f0875bb6e0c96db6172d8a388d6a00
Last-Modified: Tue, 03 Jun 2014 14:31:40 BRT
{
 "page": 1,
 "pageSize": 20,
 "numberOfPages": 1,
 "numberOfItems": 1,
 "scans": [
  {
   "status": "WAITINGEXECUTION",
   "scheduledAt": "0001-01-01T00:00:00Z",
   "startedAt": "2014-06-03T14:31:34.878-03:00",
   "finishedAt": "0001-01-01T00:00:00Z",
   "links": [
    {
     "types": [
      "self"
     ],
     "href": "/scan/2014-06-03T14:31:34.878-03:00"
    }
   ]
  }
 ],
 "links": [
  {
   "types": [
    "current"
   ],
   "href": "/scan/current"
  }
 ]
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally