Understanding How The API Works

General Information

Dyn’s REST API allows for simple HTTPS interaction with a variety of data encoding formats available.

REST, short for Representational State Transfer, is a style of software architecture for distributed hypermedia systems such as the World Wide Web.

The general approach that the Dyn’s DNS API uses for REST maps each of the common CRUD (Create, Read, Update, Delete) operations to one of the HTTP functions. The help topics are named by function key words. For Example: REST\Contact POST = Create a new Contact.

CRUD Operations, their equivalent HTTP Function, and Help Topic Key Word

For more information, see the Wikipedia article on REST.

Getting Started

There are a few things that you will need to know about connecting to the DynECT REST API.

1. Content Type

Supported content types for the REST interface.

• JSON (application/json)
• XML (text/xml)
• YAML (application/yaml)
• HTML/Query String (text/html) (limited functionality, see note below)

1. Select your content type from the list.
2. Make sure that the appropriate MIME type (the value in parenthesis above) is passed with each request as the HTTP header “Content-Type”.

NOTE: The HTML/Query String content-type has limited functionality as there is not a consistent way to represent nested data structures.

2. Sessions

While this may be a slight departure from true REST philosophy, for security purposes the DNS API requires that a session be established. This is accomplished using the Session URI: /REST/Session/

Establishing a new session is as easy as:

1. Send a POST request with Content-Type header as described above
2. To the Session URI (/REST/Session/)
3. Pass in as arguments your customer_name, user_name, and password

If you forget one of these fields, the response will let you know. If successful, you will receive a “token” under the “data” element of the response. You have now established a session.

NOTE: It is very important that any subsequent requests to the DynECT API during the session include the following in the HTTP header:
1. “Auth-Token” = the token value received in the data element of the response.
2. “Content-Type” = The content-type chosen in the Content Type section of this document.

3. Using a Query String

REST will accept basic arguments, both scalar and array, using a query string instead of or in addition to the arguments specified in the body of the call. The syntax for the query string is as follows:

• ? – marker at the end of the URI to identify the start of the query.
• Use %20 to signify a space in the URI query. Example: argument%201=value%201&argument%202=value%202
• Nested values may not be placed within the query – use the body of the call.

NOTE #1: If you enter the same argument in both the query string AND the body of the call, the body argument value will override the query string value.

NOTE #2: Nested argument structure is too complicated to use the URI query string format. Enter any nested arguments in the body of the call.

Examples of Query String arguments:

/REST/Object?foo=bar
/REST/Object/identifier?foo=bar
/REST/Object/identifier?foo=bar&love=cheese
/REST/Object/identifier?foo=bar&foo=bar2 

4. Responses

With a very few exceptions (outlined below), the top level of the response data structure for all requests will look the same. They will contain the following items:

• job_id: The ID of the job that was created in response to a request.
• status: One of ‘success’, ‘failure’, or ‘incomplete’
• msgs: A list of zero or more messages (structure described below) regarding the results.
• data: The structure containing the actual results of the request. Format depends on the request made.

The messages contained within the msgs field will contain:

• SOURCE: A debugging field. If reporting an error to your Dynect Concierge, be sure to include this.
• LEVEL: The severity of the message. One of: ‘FATAL’, ‘ERROR’, ‘WARN’, or ‘INFO’
• INFO: The actual message itself.
• ERR_CD: An error code (if appropriate) regarding the message. Valid values:
  • DEPRECATED_REQUEST: The requested command is deprecated
  • ILLEGAL_OPERATION: The operation is not allowed with this data set
  • INTERNAL_ERROR: An error occurred that cannot be classified.
  • INVALID_DATA: A field contained data that was invalid
  • INVALID_REQUEST: The request was not recognized as a valid command
  • INVALID_VERSION: The version number passed in was invalid
  • MISSING_DATA: A required field was not provided
  • NOT_FOUND: No results were found
  • OPERATION_FAILED: The operation failed to complete successfully
  • PERMISSION_DENIED: This user does not have permission to perform this action
  • SERVICE_UNAVAILABLE: The requested service is currently unavailable.
  • TARGET_EXISTS: Attempted to add a duplicate resource
  • UNKNOWN_ERROR: An error occurred that cannot be classified

5. Jobs

Each request to the DynECT API will cause a “job” to be created. The Job ID will be one of the fields in a response. You can use the /REST/Job/ resource to retrieve the results of a job so long as your session is active.

Long Running Jobs:
If a request takes longer than 5 seconds to generate data, the API will instead respond with a Temporary Redirect (HTTP 307) and the URI of the Job. Your program can then periodically check the job results until they become available. It is recommended that a GetJob command be run no more than once every 5 seconds as running it more frequently will lead to the maximum number of redirects and produce an error. The job’s status will be ‘incomplete’ until it finishes. This is designed to keep your programs from hanging while awaiting their response.

NOTE: The API will not permit another request to begin until the previous one has finished.

6. Version

In an attempt to keep the API from having unexpected changes, the API protocol supports specifying a version. Calls made against a particular version of the API should stay reasonably consistent over time.

If a requester does not specify a version in a request, the most recent version will be used. The current version will also be returned as a part of the response data to a successful POST to /REST/Session/. This does not limit a specific session to a particular version – each request can specify the version of the API to use.

In order to specify a particular version of the API to use with the REST interface, specify it in each request as the HTTP header, “API-Version”. Specifying a version that is unknown to the API service will result in an error.

Resources List

Nearly all functionality that is available via the Dynect web interface is also available via our API. Here are a list of all the available REST resources.

DNS API Knowledge Base