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

For security purposes the Dynect API requires that a session be established. This is accomplished using issuing a SessionLogin request.

The SessionLogin request will return a token that will be included in all other requests.

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

Responses that indicate ‘failure’ in the status field will be returned in a SOAP 1.1 Fault structure. The detail element of the Fault will contain the response formed as described above. Most SOAP 1.1 compliant client libraries are able to understand and interpret a Fault into a structure the consumer of the API can operate on. Some of these libraries create an exception in this case. However, there are libraries that are not able to parse a Fault. If you are using one of these libraries, you will need to learn about how to use the fault_incompat parameter. See libs to see if your library is listed and requires fault_incompat.

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 issue a GetJob request to retrieve the results of a job so long as your session is active.

In an effort to keep client programs from hanging while awaiting a response, if a request that is made is taking too long to generate data, the API will instead respond with a status of ‘incomplete’ and include the job_id. The timeout for this is currently 5 seconds. Your program can then periodically check the job results until they become available. The job’s status will be ‘incomplete’ until it finishes.

It is worth noting that the API will not permit another request to begin until the previous one has finished.

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 SessionLogin call. 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 SOAP interface, specify it in each request as as an extra argument, “version”. Specifying a version that is unknown to the API service will result in an error.

The latest WSDL can always be grabbed from https://api2.dynect.net/wsdl/current/Dynect.wsdl.

Specific versions can be grabbed from https://api2.dynect.net/wsdl/[version]/Dynect.wsdl where [version] is in the form of major.minor.sub (e.g. 3.0.0).

It should be noted that when you use /current/, you’re really instructing your libs to use whatever version is currently the latest. This means that if you generate your libs once from the WSDL from /current/, even if the API version is bumped, your libs will continue to use the older version until you re-request the WSDL and rebuild them.

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 SOAP commands.

DNS API Knowledge Base