diff --git a/api/approve-batchchange.html b/api/approve-batchchange.html new file mode 100644 index 000000000..a1fa793b9 --- /dev/null +++ b/api/approve-batchchange.html @@ -0,0 +1,210 @@ +VinylDNS: Approve Batch Change

Approve Batch Change

+ +

Manually approves a batch change in pending review status given the batch change ID, resulting in revalidation and +submission for backend processing. Only system administrators (ie. support or super user) can manually review a batch +change. In the event that a batch change is approved and still encounters non-fatal errors, it will remain in manual +review state until a successful approval (202 Accepted) or rejection (200 OK).

+ +

Note: If manual review is disabled in the VinylDNS instance, +users trying to access this endpoint will encounter a 404 Not Found response since it will not exist.

+ +

HTTP REQUEST

+ +
+

POST /zones/batchrecordchanges/{id}/approve

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
idstringyesUnique identifier assigned to each created batch change.
reviewCommentstringnoOptional approval explanation.
+ +

EXAMPLE HTTP REQUEST

+
{
+    "reviewComment": "Comments are optional."
+}
+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
202OK Batch change is approved and is returned in response body. Batch change is submitted for backend processing.
400BadRequest Batch change is not in pending approval status.
403Forbidden User is not a system administrator (ie. support or super user) or is attempting to approve a scheduled batch prior to its scheduled due date.
404NotFound Batch change does not exist.
+ +

Since we re-run validations upon successful approval, the create batch error codes still hold, so it is possible to see them as well.

+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
userIdstringThe unique identifier of the user that created the batch change.
userNamestringThe username of the user that created the batch change.
commentsstringConditional: comments about the batch change, if provided.
createdTimestampdate-timeThe timestamp (UTC) when the batch change was created.
changesArray of SingleChangeArray of single changes within a batch change. A SingleChange can either be a SingleAddChange or a SingleDeleteRRSetChange.
statusBatchChangeStatusStatus of the batch change.
idstringThe unique identifier for this batch change.
ownerGroupIdstringConditional: Record ownership assignment, if provided.
approvalStatusBatchChangeApprovalStatusWhether the batch change is currently awaiting manual review. Will be ManuallyApproved status when approving.
reviewerIdstringUnique identifier for the reviewer of the batch change.
reviewerUserNamestringUser name for the reviewer of the batch change.
reviewCommentstringConditional: Comment from the reviewer of the batch change, if provided.
reviewTimestampdate-timeThe timestamp (UTC) of when the batch change was manually reviewed.
+ +

EXAMPLE RESPONSE

+ +
{
+    "userId": "vinyl",
+    "userName": "vinyl201",
+    "comments": "",
+    "createdTimestamp": "2019-07-25T20:08:17Z",
+    "changes": [
+        {
+            "changeType": "Add",
+            "inputName": "approve.parent.com.",
+            "type": "A",
+            "ttl": 7200,
+            "record": {
+                "address": "1.1.1.1"
+            },
+            "status": "Pending",
+            "recordName": "approve",
+            "zoneName": "parent.com.",
+            "zoneId": "876879e5-293d-4092-99ab-9cbdf50c1636",
+            "validationErrors": [],
+            "id": "a69cad97-994d-41e3-aed2-ec8c86a30ac5"
+        }
+    ],
+    "status": "PendingProcessing",
+    "id": "2343fa88-d4da-4377-986a-34ba4e8ca628",
+    "ownerGroupId": "159a41c5-e67e-4951-b539-05f5ac788139",
+    "reviewerId": "90c11ffc-5a71-4794-97c6-74d19c81af7d ",
+    "reviewComment": "Good to go!",
+    "reviewTimestamp": "2019-07-25T20:10:28Z",
+    "approvalStatus": "ManuallyApproved"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/auth-mechanism.html b/api/auth-mechanism.html new file mode 100644 index 000000000..1480b52ac --- /dev/null +++ b/api/auth-mechanism.html @@ -0,0 +1,67 @@ +VinylDNS: Authentication

API Authentication

+ +

The API Authentication for VinylDNS is modeled after the AWS Signature Version 4 Signing process. The AWS documentation +for it can be found +here. Similar to how the AWS Signature Version +4 signing process adds authentication information to AWS requests, VinylDNS’s API Authenticator also adds authentication +information to every API request.

+ +

VinylDNS API Authentication Process

+ +
    +
  1. Retrieve the Authorization HTTP Header (Auth Header) from the HTTP Request Context.
    2. +
  2. Parse the retrieved Auth Header into an +AWS String to Sign structure +which should be in the form:
    3. +
+ +
StringToSign =
+    Algorithm + \n +
+    RequestDateTime + \n +
+    CredentialScope + \n +
+    HashedCanonicalRequest
+
+ +

String to Sign Example:

+ +
AWS4-HMAC-SHA256
+20150830T123600Z
+20150830/us-east-1/iam/aws4_request
+f536975d06c0309214f805bb90ccff089219ecd68b2577efef23edd43b7e1a59
+
+ +
    +
  1. Extract the access key from the Auth Header and search for the account associated with the access key.
    2. +
  2. Validate the signature of the request.
    3. +
  3. Build the authentication information, which essentially contains all the authorized accounts for the signed in user.
    4. +
+ +

Authentication Failure Response

+ +

If any these validations fail, a 401 (Unauthorized) or a 403 (Forbidden) error will be thrown; otherwise unanticipated +exceptions will simply bubble out and result as 500s or 503s.

+ +
    +
  1. If the Auth Header is not found, then a 401 (Unauthorized) error is returned.
    2. +
  2. If the Auth Header cannot be parsed, then a 403 (Forbidden) error is returned.
    3. +
  3. If the access key cannot be found, then a 401 (Unauthorized) error is returned.
    4. +
  4. If the request signature cannot be validated, then a 403 (Forbidden) error is returned.
    5. +
+
Improve this page
\ No newline at end of file diff --git a/api/batchchange-errors.html b/api/batchchange-errors.html new file mode 100644 index 000000000..06658d133 --- /dev/null +++ b/api/batchchange-errors.html @@ -0,0 +1,571 @@ +VinylDNS: Batch Change Errors

Batch Change Errors

+ + +

SINGLE CHANGE ERRORS

+

Single change errors are errors that get collected at different validation stages and correspond to individual +change inputs. Each change can have its own list of one or more errors. Single change errors are grouped into the following stages:

+ +
    +
  • Independent input validations: Validate invalid data input formats and values.
    • +
  • Record and zone discovery: Resolve record and zone from fully-qualified input name.
    • +
  • Dependent context validations: Check for sufficient user access and conflicts with existing records or other submissions within the batch.
    • +
+ +

Since single change errors are collected at different stages, errors at later stages may exist but will not +appear unless errors at earlier stages are addressed. An example is that a user may initially get an error about required data +missing from the DNS request, and then after correcting the data encounter an issue about a conflicting record already existing +in the DNS backend.

+ +

EXAMPLE ERROR RESPONSE BY CHANGE

+ +
[
+   {
+      "changeType": "Add",
+      "inputName": "good-A.another.example.com.",
+      "type": "A",
+      "ttl": 200,
+      "record": {
+        "address": "1.2.3.4"
+      }
+   },
+   {
+      "changeType": "Add",
+      "inputName": "duplicate.example.com",
+      "type": "CNAME",
+      "ttl": 200,
+      "record": {
+         "cname": "test.example.com."
+      },
+      "errors": [
+         "Record with name \"duplicate.example.com.\" is not unique in the batch change. CNAME record cannot use duplicate name."
+      ]
+   },
+   {
+      "changeType": "Add",
+      "inputName": "duplicate.example.com",
+      "type": "A",
+      "ttl": 300,
+      "record": {
+         "address": "1.2.3.4"
+      }
+   },
+   {
+      "changeType": "Add",
+      "inputName": "bad-ttl-and-invalid-name$.sample.com.",
+      "type": "A",
+      "ttl": 29,
+      "record": {
+         "address": "1.2.3.4"
+      },
+      "errors": [
+         "Failed validation 29, TTL must be between 30 and 2147483647.",
+         "Failed validation bad-ttl-and-invalid-name$.sample.com., valid domain names are a series of one or more labels joined by dots and terminate on a dot."
+      ]
+   }
+]
+
+ +

Single Change Errors

+

Single change errors can be further classified as non-fatal or fatal errors. The presence of one or more fatal +errors will result in an immediate failure (ie. hard stop) and no changes in the batch will be accepted. The behavior of non-fatal errors depends +on whether manual review is configured on: if manual review +is disabled, non-fatal errors are treated as fatal errors; if manual review is enabled, batches with only non-fatal errors will enter +a pending review state.

+ +

When non-fatal errors are encountered with manual review enabled, the errors will be saved on the corresponding SingleChanges. +The SingleChanges will also have a status of NeedsReview.

+ +

The following chart provides a breakdown of batch change status outcome based on a combination of manual review +configuration and error types present in the batch change:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Manual Review Enabled?Errors in Batch?Status Outcome
YesBoth fatal and non-fatalHard stop
YesFatal onlyHard stop
YesNon-fatal onlyPendingReview
YesNoPendingProcessing (will be or is being auto-processed)
NoBoth fatal and non-fatalHard stop
NoFatal onlyHard stop
NoNon-fatal onlyFailed
NoNoPendingProcessing (will be or is being auto-processed)
+ +

Note: if a user submits a batch change with allowManualReview set to false, the request will treat the request as though +the VinylDNS instance is configured to have manual review disabled.

+ +
Non-Fatal Errors
+ + + +
Fatal Errors
+ + + +

Non-Fatal Errors

+

Zone Discovery Failed

+ +
Error Message:
+ +
Zone Discovery Failed: zone for "<input>" does not exist in VinylDNS. If zone exists, then it must be connected to in VinylDNS.
+
+ +
Details:
+ +

Given an inputName, VinylDNS will determine the record and zone name for the requested change. For most records, the record +names are the same as the zone name (apex), or split at at the first ‘.’, so the inputName ‘rname.zone.name.com’ will be split +into record name ‘rname’ and zone name ‘zone.name.com’ (or ‘rname.zone.name.com’ for both the record and zone name if it’s an apex record). +For PTR records, there is logic to determine the appropriate reverse zone from the given IP address.

+ +

If this logic cannot find a matching zone in VinylDNS, you will see this error. +In that case, you need to connect to the zone in VinylDNS. +Even if the zone already exists outside of VinylDNS, it has to be added to VinylDNS to modify records. +VinylDNS also does not support dotted records for forward zones (eg. record baz.foo.bar. in zone bar.), so encountering +this error could indicate that a zone needs to be created outside of VinylDNS and then connected to within VinylDNS.

+ +

Record Requires Manual Review

+ +
Error Message:
+ +
Record set with name <input> requires manual review.
+
+ +
Details:
+ +

Based on a configurable list, VinylDNS will determine if the given inputName requires manual review before it can be processed.

+ +

Fatal Errors

+

Invalid Domain Name

+ +
Error Message:
+ +
Invalid domain name: "<input>", valid domain names must be letters, numbers, underscores, and hyphens, joined by dots, and terminate with a dot.
+
+ +
Details:
+ +

Fully qualified domain names, must be comprised of labels, separated by dots. +A label is a combination of letters, digits, underscores, and hyphens. +They must also be absolute, which means they end with a dot.

+ +

Syntax:

+ +
<domain> ::= <subdomain> | " "
+
+<subdomain> ::= <label> | <subdomain> "." <label>
+
+<label> ::= <letter> [ [ <ldh-str> ] <let-dig> ]
+
+<ldh-str> ::= <let-dig-hyp> | <let-dig-hyp> <ldh-str>
+
+<let-dig-hyp> ::= <let-dig> | "-"
+
+<let-dig> ::= <letter> | <digit>
+
+<letter> ::= any one of the 52 alphabetic characters A through Z in
+upper case and a through z in lower case
+
+<digit> ::= any one of the ten digits 0 through 9
+
+ +

More info can be found at:

+ +

RFC 1035, DOMAIN NAMES - IMPLEMENTATION AND SPECIFICATION, Section 2.3.1. Preferred name syntax

+ +

Invalid Length

+ +
Error Message:
+ +
Invalid length: "<input>", length needs to be between <minLengthInclusive> and <maxLengthInclusive> characters.
+
+ +
Details:
+ +

The length of the input did not fit in the range in [minLengthInclusive, maxLengthInclusive].

+ +

Invalid Record Type

+ +
Error Message:
+ +
Invalid record type: "<input>", valid record types include <valid record types>.
+
+ +
Details:
+ +

The record type input must match one of the valid record types. Not all DNS record types are currently supported.

+ +

Invalid IPv4 Address

+ +
Error Message:
+ +
Invalid IPv4 address: "<input>"
+
+ +
Details:
+ +

The IPv4 address input is not a valid IPv4 address. Accepted inputs must be in dotted-decimal notation, with four +groups of three decimal digits, separated by periods. Leading zeros in groups can be omitted.

+ +

Range: 0.0.0.0 - 255.255.255.255

+ +

Examples:

+ +
    +
  • 1.1.1.1
    • +
  • 10.234.0.62
    • +
+ +

Invalid IPv6 Address

+ +
Error Message:
+ +
Invalid IPv6 address: "<input>".
+
+ +
Details:
+ +

The IPv6 address input is not a valid IPv6 address. Accepted inputs must be eight groups of four hexadecimal digits, +separated by colons. Leading zeros in groups can be emitted. Consecutive groups of all zeros can be replaced by a double colon.

+ +

Range: 0000:0000:0000:0000:0000:0000:0000:0000 - ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

+ +

Examples:

+ +
    +
  • 2001:0db8:0000:0000:0000:ff00:0042:8329
    • +
  • 2001:0db8::ff00:0042:8329
    • +
  • 2001:db8::ff00:42:8329
    • +
+ +

Invalid IP Address

+ +
Error Message:
+ +
Invalid IP address: "<input>".
+
+ +
Details:
+ +

The IP address input is not a valid IPv4 or IPv6 address.

+ +

Invalid TTL

+ +
Error Message:
+ +
Invalid TTL: "<input>", must be a number between 30 and 2147483647.
+
+ +
Details:
+ +

Time-to-live must be a number in the range [30, 2147483647].

+ +

Invalid Batch Record Type

+ +
Error Message:
+ +
Invalid Batch Record Type: "<input>", valid record types for batch changes include <valid record types>.
+
+ +
Details:
+ +

The DNS record type is not currently supported for batch changes.

+ +

Record Already Exists

+ +
Error Message:
+ +
Record "<input>" Already Exists: cannot add an existing record; to update it, issue a DeleteRecordSet then an Add.
+
+ +
Details:
+ +

A record with the given name already exists, and cannot be duplicated for the given type.

+ +

Record Does Not Exist

+ +
Error Message:
+ +
Record "<input>" Does Not Exist: cannot delete a record that does not exist.
+
+ +
Details:
+ +

A record with the given name could not be found in VinylDNS. +If the record exists in DNS, then you should sync the zone for that record to bring VinylDNS up to date with what is in the DNS backend.

+ +

CNAME Conflict

+ +
Error Message:
+ +
CNAME conflict: CNAME record names must be unique. Existing record with name "<name>" and type "<type>" conflicts with this record.
+
+ +
Details:
+ +

A CNAME record with the given name already exists. CNAME records must have unique names.

+ +

User Is Not Authorized

+ +
Error Message:
+ +
User "<user>" is not authorized.
+
+ +
Details:
+ +

User must either be in the admin group for the zone being changed, or have an ACL rule.

+ +

Record Name Not Unique In Batch Change

+ +
Error Message:
+ +
Record "<name>" Name Not Unique In Batch Change: cannot have multiple "<type>" records with the same name.
+
+ +
Details:
+ +

Certain record types do not allow multiple records with the same name. If you get this error, it means you have +illegally input two or more records with the same name and one of these types.

+ +

Invalid Record Type In Reverse Zone

+ +
Error Message:
+ +
Invalid Record Type In Reverse Zone: record with name "<name>" and type "<type>" is not allowed in a reverse zone.
+
+ +
Details:
+ +

Not all record types are allowed in a DNS reverse zone. The given type is not supported.

+ +

Missing Owner Group Id

+ +
Error Message:
+ +
Zone "<zone name>" is a shared zone, so owner group ID must be specified for record "<record name>".
+
+ +
Details:
+ +

You are trying to create a new record or update an existing unowned record in a shared zone. This requires a record owner group ID in the batch change.

+ +

Not a Member of Owner Group

+ +
Error Message:
+ +
User "<user name>" must be a member of group "<group ID>" to apply this group to batch changes.
+
+ +
Details:
+ +

You must be a member of the group you are assigning for record ownership in the batch change.

+ +

High Value Domain

+ +
Error Message:
+ +
Record Name "<record name>" is configured as a High Value Domain, so it cannot be modified.
+
+ +
Details:
+ +

You are trying to create a record with a name that is not permitted in VinylDNS. +The list of high value domains is specific to each VinylDNS instance. +You should reach out to your VinylDNS administrators for more information.

+ +

CNAME at the Zone Apex is not Allowed

+ +
Error Message:
+ +
CNAME cannot be the same name as zone "<zone_name>".
+
+ +
Details:
+ +

CNAME records cannot be @ or the same name as the zone.

+ +

FULL-REQUEST ERRORS

+ +

Fail-request errors cause the batch change processing to abort immediately upon encounter.

+ + + +

1. INVALID BATCH CHANGE INPUT

+ +
HTTP RESPONSE CODE
+ + + + + + + + + + + + + + +
Codedescription
400Bad Request - There is a top-level issue with batch change, aborting batch processing.
+ +

There are a series of different error messages that can be returned with this error code.

+ +
EXAMPLE ERROR MESSAGES:
+ +
Batch change contained no changes. Batch change must have at least one change, up to a maximum of <limit> changes.
+
+Cannot request more than <limit> changes in a single batch change request
+
+ +
DETAILS:
+ +

If there are issues with the batch change input data provided in the batch change request, errors will be returned and batch change validations will abort processing.

+ +

BATCH CHANGE NOT FOUND

+ +
HTTP RESPONSE CODE
+ + + + + + + + + + + + + + +
Codedescription
404Not Found - batch change not found for specified ID in get batch change request.
+ +
ERROR MESSAGE:
+ +
Batch change with id <id> cannot be found
+
+ +
DETAILS:
+ +

The batch ID specified in the get batch change request does not exist.

+ +

MALFORMED JSON ERRORS

+ +
DETAILS:
+ +

If there are issues with the JSON provided in a batch change request, errors will be returned (not in a single change format) and none of the batch change validations will run.

+ +
EXAMPLE ERROR MESSAGES:
+ +
{
+   "errors": [
+      "Missing BatchChangeInput.changes"
+   ]
+}
+
+{
+   "errors": [
+      "Missing BatchChangeInput.changes.inputName",
+      "Missing BatchChangeInput.changes.type",
+      "Missing BatchChangeInput.changes.ttl"
+   ]
+}
+
+{
+   "errors": [
+      "Invalid RecordType""
+   ]
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/batchchange-model.html b/api/batchchange-model.html new file mode 100644 index 000000000..8ab72ea94 --- /dev/null +++ b/api/batchchange-model.html @@ -0,0 +1,391 @@ +VinylDNS: Batch Change Model

Batch Change Model

+ +

Table of Contents

+ + + +

BATCH CHANGE INFORMATION

+ +

Batch change is an alternative to submitting individual RecordSet changes and provides the following:

+ +
    +
  • The ability to accept multiple changes in a single API call.
    • +
  • The ability to include records of multiple record types across multiple zones.
    • +
  • Input names are entered as fully-qualified domain names (or IP addresses for PTR records), so users don’t have to think in record/zone context.
    • +
  • All record validations are processed simultaneously. Fatal errors for any +change in the batch will result in a 400 response and none will be applied.
    • +
  • Support for manual review if enabled in your VinylDNS instance. +Batch change will remain in limbo until a system administrator (ie. support or super user) either rejects it resulting in +an immediate failure or approves it resulting in revalidation and submission for processing.
    • +
  • Support for notifications when a batch change is rejected or implemented.
    • +
+ +

A batch change consists of multiple single changes which can be a combination of SingleAddChanges and SingleDeleteRRSetChanges.

+ +

Note: In the portal batch change is referred to as DNS Change.

+ +

To update an existing record, you must delete the record first and add the record again with the updated changes.

+ +

Batch changes are also susceptible to the following restrictions:

+
    +
  • Current supported record types for batch change are: A, AAAA, CNAME, and PTR.
    • +
  • Batch change requests must contain at least one change.
    • +
  • The maximum number of single changes within a batch change depends on the instance of VinylDNS. Contact your VinylDNS administrators to find the batch change limit for your instance.
    • +
  • Access permissions will follow existing rules (admin group or ACL access). Note that an update (delete and add of the same record name, zone and record type combination) requires Write access.
    • +
+ +

BATCH CHANGE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
userIdstringThe unique identifier of the user that created the batch change.
userNamestringThe username of the user that created the batch change.
commentsstringOptional comments about the batch change.
createdTimestampdate-timeThe timestamp (UTC) when the batch change was created.
changesArray of SingleChangeArray of single changes within a batch change. A SingleChange can either be a SingleAddChange or a SingleDeleteRRSetChange.
statusBatchChangeStatus- PendingProcessing - at least one change in batch has not finished processing
- Complete - all changes have been processed successfully
- Failed - all changes failed during processing
- PartialFailure - some changes have failed and the rest were successful
- PendingReview - one or more changes requires manual approval/rejection by a system administrator (ie. super or support user) to proceed
- Rejected - the batch change was rejected by a system administrator (ie. super or support user) and no changes were applied
- Scheduled - the batch change is scheduled for a later date at which time it needs to be approved to proceed.
- Cancelled - the PendingReview batch change was cancelled by its creator before review.
idstringThe unique identifier for this batch change.
ownerGroupIdstringRecord ownership assignment. Required if any records in the batch change are in shared zones and are new or unowned.
approvalStatusBatchChangeApprovalStatusWhether the batch change is currently awaiting manual review. Can be one of AutoApproved, PendingReview, ManuallyApproved, Rejected, or Cancelled.
reviewerIdstringOptional unique identifier for the reviewer of the batch change. Required if batch change was manually rejected or approved.
reviewerUserNamestringOptional user name for the reviewer of the batch change. Required if batch change was manually rejected or approved.
reviewCommentstringOptional comment for the reviewer of the batch change. Only applicable if batch change was manually rejected or approved.
reviewTimestampdate-timeOptional timestamp (UTC) of when the batch change was manually reviewed. Required if batch change was manually rejected or approved.
scheduledTimedate-timeOptional requested date and time to process the batch change.
cancelledTimestampdate-timeOptional date and time a batch change was cancelled by its creator.
+ +

SINGLE CHANGE ATTRIBUTES

+ +

A successful batch change response consists of a corresponding SingleAddChange or SingleDeleteRRSetChange for each batch change input. See the batch change create page for details on constructing a batch change request.

+ +

SingleAddChange

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
changeTypeChangeInputTypeType of change input. Can either be an Add or DeleteRecordSet. See more details about behavior of changeType interaction.
inputNamestringThe fully-qualified domain name of the record which was provided in the create batch request.
typeRecordTypeType of DNS record, supported records for batch changes are currently: A, AAAA, CNAME, and PTR.
ttllongThe time-to-live in seconds.
recordRecordDataThe data added for this record, which varies by record type.
statusSingleChangeStatusStatus for this change. Can be one of: Pending, Complete, Failed, NeedsReview or Rejected.
recordNamestringThe name of the record. Record names for the apex will be match the zone name (including terminating dot).
zoneNamestringThe name of the zone.
zoneIdstringThe unique identifier for the zone.
systemMessagestringConditional: Returns system message relevant to corresponding batch change input.
recordChangeIdstringConditional: The unique identifier for the record change; only returned on successful batch creation.
recordSetIdstringConditional: The unique identifier for the record set; only returned on successful batch creation,
validationErrorsArray of BatchChangeErrorArray containing any validation errors associated with this SingleAddChange. Note: These will only exist on NeedsReview or Rejected SingleChanges
idstringThe unique identifier for this change.
+ +

SingleDeleteRRSetChange

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
changeTypeChangeInputTypeType of change input. Can either be an Add or DeleteRecordSet. See more details about behavior of changeType interaction.
inputNamestringThe fully-qualified domain name of the record which was provided in the create batch request.
typeRecordTypeType of DNS record, supported records for batch changes are currently: A, AAAA, CNAME, and PTR.
recordRecordDataOptional. The data deleted for this record, which varies by record type. If not provided, the entire DNS recordset was deleted.
statusSingleChangeStatusStatus for this change. Can be one of: Pending, Complete, Failed, NeedsReview or Rejected.
recordNamestringThe name of the record. Record names for the apex will be match the zone name (including terminating dot).
zoneNamestringThe name of the zone.
zoneIdstringThe unique identifier for the zone.
systemMessagestringConditional: Returns system message relevant to corresponding batch change input.
recordChangeIdstringConditional: The unique identifier for the record change; only returned on successful batch creation.
recordSetIdstringConditional: The unique identifier for the record set; only returned on successful batch creation,
validationErrorsArray of BatchChangeErrorArray containing any validation errors associated with this SingleDeleteRRSetChange. Note: These will only exist on NeedsReview or Rejected SingleChanges
idstringThe unique identifier for this change.
+ +

ChangeType Values

+ +

There are two valid changeTypes for a SingleChange: Add and DeleteRecordSet

+ +

changeTypes can be used independently or combined to achieve the desired behavior described below.

+ +
    +
  • Create a new DNS record: Add with record data
    • +
  • Delete an entire record set: 1. DeleteRecordSet without specifying existing record data or 2. DeleteRecordSet for each entry of the DNS record
    • +
  • Delete a single entry from DNS record with multiple entries: DeleteRecordSet specifying existing record data
    • +
  • Update an existing record set: 1. DeleteRecordSet specifying existing record data (single entry delete) or not specifying record data (full delete) and 2. Add with record data
    • +
+ +

BATCH CHANGE EXAMPLE

+ +

Successful batch change response example with a SingleAddChange and a SingleDeleteRRSetChange.

+ +
{
+    "userId": "vinyl", 
+    "userName": "vinyl201", 
+    "comments": "this is optional", 
+    "createdTimestamp": "2018-05-08T18:46:34Z", 
+    "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe"
+    "changes": [
+        {
+            "changeType": "Add",
+            "inputName": "recordName.zoneName.", 
+            "type": "A", 
+            "ttl": 3600,  
+            "record": {
+                "address": "1.1.1.1"
+            },
+            "status": "Complete", 
+            "recordName": "recordName", 
+            "zoneName": "zoneName.", 
+            "zoneId": "8f8f649f-998e-4428-a029-b4ba5f5bd4ca",
+            "recordChangeId": "4754ac4c-5f81-11e8-9c2d-fa7ae01bbebc",
+            "recordSetId": "4754b084-5f81-11e8-9c2d-fa7ae01bbebc",
+            "validationErrors": [],
+            "id": "17350028-b2b8-428d-9f10-dbb518a0364d"
+        }, 
+        {
+            "changeType": "DeleteRecordSet",
+            "inputName": "recordName.zoneName.", 
+            "type": "AAAA", 
+            "status": "Complete", 
+            "recordName": "recordName", 
+            "zoneName": "zoneName.", 
+            "zoneId": "9cbdd3ac-9752-4d56-9ca0-6a1a14fc5562",
+            "recordChangeId": "4754b322-5f81-11e8-9c2d-fa7ae01bbebc",
+            "recordSetId": "4754b084-5f81-11e8-9c2d-fa7ae01bbebc",
+            "validationErrors": [],
+            "id": "c29d33e4-9bee-4417-a99b-6e815fdeb748"
+        },
+        {
+            "changeType": "DeleteRecordSet",
+            "inputName": "anotherRecordName.zoneName.",
+            "type": "A",
+            "record": {
+                "address": "1.1.1.1"
+            },
+            "status": "Complete",
+            "recordName": "recordName",
+            "zoneName": "zoneName.",
+            "zoneId": "9cbdd3ac-9752-4d56-9ca0-6a1a14fc5562",
+            "recordChangeId": "9c449026-cffe-4379-beb7-217b8a31aadd",
+            "recordSetId": "e68776ab-f56f-41bf-a03e-c288b9469b53",
+            "validationErrors": [],
+            "id": "e68776ab-f56f-41bf-a03e-c288b9469b53"
+        }
+    ], 
+    "status": "Complete", 
+    "id": "937191c4-b1fd-4ab5-abb4-9553a65b44ab",
+    "approvalStatus": "AutoApproved"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/cancel-batchchange.html b/api/cancel-batchchange.html new file mode 100644 index 000000000..34a13af0d --- /dev/null +++ b/api/cancel-batchchange.html @@ -0,0 +1,80 @@ +VinylDNS: Cancel Batch Change

Cancel Batch Change

+ +

Cancels a batch change that is PendingReview. Only the user who created the batch change can cancel it.

+ +

Note: If manual review is disabled in the VinylDNS instance, +users trying to access this endpoint will encounter a 404 Not Found response since it will not exist.

+ +

HTTP REQUEST

+ +
+

POST /zones/batchrecordchanges/{id}/cancel

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + +
nametyperequired?description
idstringyesUnique identifier assigned to each created batch change.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The batch change is returned in response body.
403Forbidden - The user does not have the access required to perform the action.
404Not Found - Batch change not found.
+ +

HTTP RESPONSE ATTRIBUTES

+ +

See Batch Change Model attributes

+
Improve this page
\ No newline at end of file diff --git a/api/create-batchchange.html b/api/create-batchchange.html new file mode 100644 index 000000000..7c1baf263 --- /dev/null +++ b/api/create-batchchange.html @@ -0,0 +1,334 @@ +VinylDNS: Create Batch Change

Create Batch Change

+ +

Creates a batch change with SingleAddChanges and/or SingleDeleteRRSetChanges across different zones. A delete and add of the same record will be treated as an update on that record set. Regardless of the input order in the batch change, all deletes for the same recordset will be logically applied before the adds.

+ +

Current supported record types for creating a batch change are: A, AAAA, CNAME, MX, PTR, TXT. A batch must contain at least one change and no more than 20 changes. +Supported record types for records in shared zones may vary. Contact your VinylDNS administrators to find the allowed record types. +This does not apply to zone administrators or users with specific ACL access rules.

+ +

HTTP REQUEST

+ +
+

POST /zones/batchrecordchanges?allowManualReview={true | false}

+
+ +

Note that the batch change request inputs are a subset of the full batch change model.

+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
commentsstringnoOptional comments about the batch change.
changesArray of ChangeInputyesSet of ChangeInputs in the batch change. A ChangeInput is an AddChangeInput or DeleteChangeInput. Type is inferred from specified changeType.
ownerGroupIdstringsometimesRecord ownership assignment. Required if any records in the batch change are in shared zones and are new or unowned.
scheduledTimedate-timenoOptional datetime. Stored as UTC. Batch change will not be processed until after the scheduled time. Required format is an ISO 8601 date time string.
allowManualReviewbooleannoOptional override to control whether manual review is enabled for the batch change request. Default value is true. Must be passed in as a query parameter, not in the request body.
+ +
AddChangeInput
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
changeTypeChangeInputTypeyesType of change input. Must be set to Add for AddChangeInput.
inputNamestringyesThe fully qualified domain name of the record being added. For PTR, the input name is a valid IPv4 or IPv6 address.
typeRecordTypeyesType of DNS record. Supported records for batch changes are currently: A, AAAA, CNAME, and PTR.
ttllongnoThe time-to-live in seconds. The minimum and maximum values are 30 and 2147483647, respectively. If excluded, this will be set to the system default for new adds, or the existing TTL for updates
recordRecordDatayesThe data for the record.
+ +
DeleteChangeInput
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
changeTypeChangeInputTypeyesType of change input. Must be DeleteRecordSet for DeleteChangeInput.
inputNamestringyesThe fully qualified domain name of the record being deleted.
typeRecordTypeyesType of DNS record. Supported records for batch changes are currently: A, AAAA, CNAME, and PTR.
recordRecordDatanoThe data for the record. If specified, only this DNS entry for the existing DNS recordset will be deleted; if unspecified, the entire DNS recordset will be deleted.
+ +

EXAMPLE HTTP REQUEST

+
{
+    "comments": "this is optional",
+    "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe",
+    "changes": [
+        {
+            "inputName": "example.com.",
+            "changeType": "Add",
+            "type": "A",  
+            "ttl": 3600, 
+            "record": {
+                "address": "1.1.1.1"
+            } 
+        }, 
+        {
+            "inputName": "192.0.2.195",
+            "changeType": "Add",
+            "type": "PTR", 
+            "ttl": 3600,
+            "record": {
+                "ptrdname": "ptrdata.data."
+            }
+        }, 
+        {
+            "inputName": "cname.example.com.",
+            "changeType": "DeleteRecordSet",
+            "type": "CNAME"
+        }, 
+        {
+            "inputName": "update.another.example.com.",
+            "changeType": "DeleteRecordSet",
+            "type": "AAAA",
+            "record": {
+              "address": "2:3:4:5:6:7:8:9" 
+            }
+        }, 
+        {
+            "inputName": "update.another.example.com.",
+            "changeType": "Add",
+            "type": "AAAA", 
+            "ttl": 4000,
+            "record": {
+                "address": "1:2:3:4:5:6:7:8"
+            }
+        }
+    ]
+}
+
+ +

The first two items in the changes list are SingleAddChanges of an A record and a PTR record. Note that for the PTR record, the inputName is a valid IP address. The third item is a delete of a CNAME record. The last two items represent an update (delete & add) of an AAAA record with the fully qualified domain name “update.another.example.com.”.

+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
202Accepted - The batch change is validated and is returned in the response body. Based on status, the batch will either be sent for immediate backend processing (PendingProcessing) or pending manual review (PendingReview).
400Bad Request - Error in the batch change. See Batch Change Errors page.
403Forbidden - The user does not have the access required to perform the action.
413Request Entity Too Large - Cannot request more than changes in a single batch change request.
422Unprocessable Entity - the batch does not contain any changes, thus cannot be processed.
+ +

A batch change goes through numerous validations before it is processed. This results in corresponding BadRequest or error responses. View the full list of batch change errors here.

+ +

HTTP RESPONSE ATTRIBUTES

+ +

On success, the response from create batch change includes the fields the user input, as well as some additional information provided by the system. This response is the same as that of get batch change.

+ +

EXAMPLE RESPONSE

+ +
{
+    "userId": "vinyl", 
+    "userName": "vinyl201", 
+    "comments": "this is optional", 
+    "createdTimestamp": "2018-05-09T14:19:34Z",
+    "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe" 
+    "changes": [
+        {
+            "changeType": "Add",
+            "inputName": "example.com.", 
+            "type": "A", 
+            "ttl": 3600, 
+            "record": {
+                "address": "1.1.1.1"
+            }, 
+            "status": "Pending", 
+            "recordName": "example.com.", 
+            "zoneName": "example.com.", 
+            "zoneId": "74e93bfc-7296-4b86-83d3-1ffcb0eb3d13",
+            "validationErrors": [],
+            "id": "7573ca11-3e30-45a8-9ba5-791f7d6ae7a7"
+        }, 
+        {
+            "changeType": "Add",
+            "inputName": "192.0.2.195", 
+            "type": "PTR", 
+            "ttl": 3600, 
+            "record": {
+                "ptrdname": "ptrdata.data."
+            }, 
+            "status": "Pending", 
+            "recordName": "195", 
+            "zoneName": "2.0.192.in-addr.arpa.", 
+            "zoneId": "7fd52634-5a0c-11e8-9c2d-fa7ae01bbebc",
+            "validationErrors": [],
+            "id": "bece5338-5a0c-11e8-9c2d-fa7ae01bbebc"
+        }, 
+        {
+            "changeType": "DeleteRecordSet", 
+            "inputName": "cname.example.com.", 
+            "type": "CNAME", 
+            "status": "Pending",
+            "recordName": "cname", 
+            "zoneName": "example.com.", 
+            "zoneId": "74e93bfc-7296-4b86-83d3-1ffcb0eb3d13",
+            "validationErrors": [],
+            "id": "02048500-5a0d-11e8-a10f-fa7ae01bbebc" 
+        }, 
+        {
+            "changeType": "DeleteRecordSet",
+            "inputName": "update.example.com.", 
+            "type": "AAAA", 
+            "status": "Pending",
+            "recordName": "update", 
+            "zoneName": "example.com.", 
+            "zoneId": "74e93bfc-7296-4b86-83d3-1ffcb0eb3d13",
+            "validationErrors": [],
+            "id": "1cee1c78-5a0d-11e8-9c2d-fa7ae01bbebc" 
+        }, 
+        {
+            "changeType": "Add",
+            "inputName": "update.another.example.com.", 
+            "type": "AAAA", 
+            "ttl": 3600, 
+            "record": {
+                "address": "1:2:3:4:5:6:7:8"
+            }, 
+            "status": "Pending", 
+            "recordName": "update", 
+            "zoneName": "another.example.com.", 
+            "zoneId": "7fd52634-5a0c-11e8-9c2d-fa7ae01bbebc",
+            "validationErrors": [],
+            "id": "43dd1226-5a0d-11e8-9c2d-fa7ae01bbebc"
+        }
+    ], 
+    "status": "PendingProcessing", 
+    "id": "02bd95f4-a32c-443b-82eb-54dbaa55b31a"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/create-group.html b/api/create-group.html new file mode 100644 index 000000000..514fbf1b1 --- /dev/null +++ b/api/create-group.html @@ -0,0 +1,200 @@ +VinylDNS: Create Group

Create Group

+ +

Creates a Group in VinylDNS

+ +

HTTP REQUEST

+ +
+

POST /groups

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
namestringyesThe name of the group. Should be one word, use hyphens if needed but no spaces
emailstringyesThe email distribution list for the group
descriptionstringnoA short description of the group if more info is needed other than the name
membersArray of User id objectsyesSet of User ids in the group
adminsArray of User id objectsyesSet of User ids that are admins of the group. All admin user ids should also be in the members array
+ +

EXAMPLE HTTP REQUEST

+ +
{
+  "name": "some-group",
+  "email": "test@example.com",
+  "description": "an example group", 
+  "members": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    }
+  ],
+  "admins": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    }
+  ]
+}
+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The group has been created and the group info is returned in the response body
400Bad Request - The group was invalid
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
404Not Found - A user id was not found
409Conflict - A group with the same name already exists
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
idstringUnique UUID of the group
namestringThe name of the group
emailstringThe email distribution list of the group
descriptionstringThe group description, the group will not have this attribute if it was not included in the create request
createdstringThe timestamp (UTC) the group was created
statusstringActive or Deleted, in this case Active
membersArray of User ID objectsIDs of members of the group including admins
adminsArray of User ID objectsIDs of admins of the group
+ +

EXAMPLE RESPONSE

+ +
{
+  "id": "6f8afcda-7529-4cad-9f2d-76903f4b1aca",
+  "name": "some-group",
+  "email": "test@example.com",
+  "description": "an example group",
+  "created": "2017-03-02T15:29:21Z",
+  "status": "Active",
+  "members": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    }
+  ],
+  "admins": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    }
+  ]
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/create-recordset.html b/api/create-recordset.html new file mode 100644 index 000000000..bfb3259da --- /dev/null +++ b/api/create-recordset.html @@ -0,0 +1,232 @@ +VinylDNS: Create RecordSet

Create RecordSet

+ +

Creates a RecordSet in a specified zone

+ +

HTTP REQUEST

+ +
+

POST /zones/{zoneId}/recordsets

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
zoneIdstringyesid of the zone where the recordset belongs
namestringyesthe name of the recordset being updated
typestringyesthe type of recordset
ttlintegeryesthe TTL in seconds
recordsarray of record datayesrecord data for recordset, see RecordSet Model
ownerGroupIdstringnoRecord ownership assignment, applicable if the recordset is in a shared zone
+ +

EXAMPLE HTTP REQUEST

+
{
+  "name": "foo",
+  "type": "A",
+  "ttl": 300,
+  "records": [
+    {
+      "address": "10.10.10.10"
+    }
+  ],
+  "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+  "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe"
+}
+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
202Accepted - The record set is valid and has been accepted for processing; the record set change resource is returned
400Bad Request - The zone specified is not Active; typically because the zone has no connection information
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - the zone with the id specified was not found
409Conflict - A record set with the same name and type already exists in the zone
422Unprocessable Entity
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zonemapContains information about the zone when the change was created
recordSetmapContains the recordset model
userIdstringThe user id that initiated the change
changeTypestringType of change requested (Create, Update, Delete); in this case Create
createdstringThe timestamp (UTC) the change was initiated
idstringThe ID of the change. This is not the ID of the recordset
statusRecordSetChangeStatusThe status of the change (Pending, Complete, or Failed)
singleBatchChangeIdsarray of SingleBatchChange Id objectsIf the recordset change was part of a batch change, the IDs of the single changes that comprise the recordset change
+ +

EXAMPLE RESPONSE

+ +
{
+  "zone": {
+    "name": "vinyl.",
+    "email": "test@test.com",
+    "status": "Active",
+    "created": "2017-02-23T14:52:44Z",
+    "id": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "shared": false,
+    "acl": {
+      "rules": [
+
+      ]
+    },
+    "adminGroupId": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae"
+  },
+  "recordSet": {
+    "type": "A",
+    "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "name": "foo",
+    "ttl": 300,
+    "status": "Pending",
+    "created": "2017-02-23T14:58:54Z",
+    "records": [
+      {
+        "address": "10.10.10.10"
+      }
+    ],
+    "id": "9a41b99c-8e67-445f-bcf3-f9c7cd1f2357",
+    "account": "0215d410-9b7e-4636-89fd-b6b948a06347",
+    "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe",
+    "ownerGroupName": "Shared Group"
+  },
+  "userId": "0215d410-9b7e-4636-89fd-b6b948a06347",
+  "changeType": "Create",
+  "status": "Pending",
+  "created": "2017-02-23T14:58:54Z",
+  "id": "fef81f0b-f439-462d-88df-c773d3686c9b",
+  "singleBatchChangeIds": []
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/create-zone.html b/api/create-zone.html new file mode 100644 index 000000000..b36323857 --- /dev/null +++ b/api/create-zone.html @@ -0,0 +1,149 @@ +VinylDNS: Create Zone

Create Zone

+ +

Connects user to an existing zone. User must be a member of the group that has access to the zone. Connection info is optional, +if no info is provided the default VinylDNS connections will be used

+ +

HTTP REQUEST

+ +
+

POST /zones

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + +
zone fields - adminGroupId, name, and email are required - refer to zone model
+ +

EXAMPLE HTTP REQUEST

+
{
+  "adminGroupId": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+  "name": "dummy.",
+  "email": "test@example.com"
+}
+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
202Accepted - The zone change is queued and is returned in the response body
400Bad Request - Connection failed, or group did not have access to the zone
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - the user does not have the access required to perform the action
409Conflict - Zone already connected to
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
statusstringStatus of zone change
zonemapRefer to zone model
createdstringThe timestamp (UTC) the change was initiated
changeTypestringType of change requested (Create, Update, Sync, Delete); in this case Create
userIdstringThe user id that initiated the change
idstringThe ID of the change. This is not the ID of the zone
+ +

EXAMPLE RESPONSE

+ +
{
+  "status": "Pending",
+  "zone": {
+    "status": "Pending",
+    "account": "test_group",
+    "name": "488e6063-7832-40f6-87d3-87dae50c690a.",
+    "created": "2016-12-28T18:00:32Z",
+    "adminGroupId": "test-group-id",
+    "email": "test@test.com",
+    "shared": false,
+    "acl": {
+      "rules": [
+
+      ]
+    },
+    "id": "8ba20b72-cfdb-49d3-9216-9100aeaee7fc"
+  },
+  "created": "2016-12-28T18:00:32Z",
+  "changeType": "Create",
+  "userId": "vinyl",
+  "id": "dd449c27-bed5-4cd5-95e6-4c54fb20d930"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/delete-group.html b/api/delete-group.html new file mode 100644 index 000000000..275676fde --- /dev/null +++ b/api/delete-group.html @@ -0,0 +1,138 @@ +VinylDNS: Delete Group

Delete Group

+ +

Deletes a Group in VinylDNS

+ +

HTTP REQUEST

+ +
+

DELETE /groups/{groupId}

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The group has been delete and the group info is returned in the response body
400Bad Request - The group could not be deleted
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - The group was not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
idstringUnique UUID of the group
namemapThe name of the group
emailstringThe email distribution list of the group
descriptionstringThe group description, the group will not have this attribute if it was not set
createdstringThe timestamp (UTC) the group was created
statusstringActive or Deleted, in this case Deleted
membersArray of User ID objectsIDs of members of the group including admins
adminsArray of User ID objectsIDs of admins of the group
+ +

EXAMPLE RESPONSE

+ +
{
+  "id": "6f8afcda-7529-4cad-9f2d-76903f4b1aca",
+  "name": "some-group",
+  "email": "test@example.com",
+  "created": "2017-03-02T15:29:21Z",
+  "status": "Deleted",
+  "members": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    },
+    {
+      "id": "c8630ebc-0af2-4c9a-a0a0-d18c590ed03e"
+    }
+  ],
+  "admins": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    }
+  ]
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/delete-recordset.html b/api/delete-recordset.html new file mode 100644 index 000000000..bd075686a --- /dev/null +++ b/api/delete-recordset.html @@ -0,0 +1,165 @@ +VinylDNS: Delete RecordSet

Delete RecordSet

+ +

Delete a RecordSet in a specified zone

+ +

HTTP REQUEST

+ +
+

DELETE /zones/{zoneId}/recordsets/{recordSetId}

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
202Accepted - the delete is valid and has been accepted for processing; the record set change resource is returned in the response body
400Bad Request - the zone being updated is not active; typically because the connection information does not exist for the zone
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - Zone or RecordSet not found
409Conflict - There is an existing pending change against this zone
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zonemapContains information about the zone when the change was created
recordSetmapContains the recordset model
userIdstringThe user ID that initiated the change
changeTypestringType of change requested (Create, Update, Delete); in this case Delete
createdstringThe timestamp (UTC) the change was initiated
idstringThe ID of the change. This is not the ID of the recordset
+ +

EXAMPLE RESPONSE

+ +
{
+  "zone": {
+    "name": "vinyl.",
+    "email": "test@test.com",
+    "status": "Active",
+    "created": "2017-02-23T14:52:44Z",
+    "updated": "2017-02-23T15:12:33Z",
+    "id": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "shared": false,
+    "acl": {
+      "rules": []
+    },
+    "adminGroupId": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "latestSync": "2017-02-23T15:12:33Z"
+  },
+  "recordSet": {
+    "type": "A",
+    "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "name": "foo",
+    "ttl": 38400,
+    "status": "PendingDelete",
+    "created": "2017-02-23T15:12:33Z",
+    "updated": "2017-02-23T15:18:27Z",
+    "records": [
+      {
+        "address": "2.2.2.2"
+      }
+    ],
+    "id": "da57c384-d6e8-4166-986d-2ca9d483f760",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae"
+  },
+  "userId": "0215d410-9b7e-4636-89fd-b6b948a06347",
+  "changeType": "Delete",
+  "status": "Pending",
+  "created": "2017-02-23T15:18:27Z",
+  "updates": {
+    "type": "A",
+    "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "name": "foo",
+    "ttl": 38400,
+    "status": "Active",
+    "created": "2017-02-23T15:12:33Z",
+    "records": [
+      {
+        "address": "2.2.2.2"
+      }
+    ],
+    "id": "da57c384-d6e8-4166-986d-2ca9d483f760",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae"
+  },
+  "id": "c46cf622-285f-4f1b-b5b2-993a5a51ea5b"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/delete-zone.html b/api/delete-zone.html new file mode 100644 index 000000000..cf2be8b26 --- /dev/null +++ b/api/delete-zone.html @@ -0,0 +1,137 @@ +VinylDNS: Delete Zone

Delete Zone

+ +

Abandons an existing zone that has already been connected to. +The zone will be disconnected from VinylDNS, but the RecordSets still exist in the backend DNS zone. +To delete the RecordSets see Delete RecordSet

+ +

Note: We do not recommend that you abandon zones, as your zone history will be lost after the Delete. This endpoint is provided in certain situations where a zone was incorrectly started.

+ +

HTTP REQUEST

+ +
+

DELETE /zones/{zoneId}

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
202Accepted - The change has been queued and is returned in the response body
400Bad Request - Zone was not empty and contains records
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - Zone not found
409Conflict - Zone is unavailable
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zonemapZone being deleted
userIdstringThe user id that initiated the change
changeTypestringType of change requested (Create, Update, Sync, Delete); in this case Delete
createdstringThe timestamp (UTC) the change was initiated
idstringThe ID of the change. This is not the ID of the zone
statusstringThe status of the zone change
+ +

EXAMPLE RESPONSE

+ +
{
+  "status": "Pending",
+  "zone": {
+    "status": "Deleted",
+    "updated": "2016-12-28T18:45:53Z",
+    "name": "443ad9ff-8f38-4540-b53f-e23a35fdfc28.",
+    "adminGroupId": "test-group-id",
+    "created": "2016-12-28T18:45:53Z",
+    "account": "test_group",
+    "email": "test@test.com",
+    "shared": false,
+    "acl": {
+      "rules": []
+    },
+    "id": "4995e883-f314-4c5f-8ee8-75003ca08ab0"
+  },
+  "created": "2016-12-28T18:45:53Z",
+  "changeType": "Delete",
+  "userId": "vinyl",
+  "id": "89c463e3-1615-42f7-8299-a0ca7ccea439"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/get-batchchange.html b/api/get-batchchange.html new file mode 100644 index 000000000..3f7b086ad --- /dev/null +++ b/api/get-batchchange.html @@ -0,0 +1,194 @@ +VinylDNS: Get Batch Change

Get Batch Change

+ +

Retrieves a batch change given the batch change ID. Only the user who created a batch change and VinylDNS administrators will have access to get it.

+ +

HTTP REQUEST

+ +
+

GET /zones/batchrecordchanges/{id}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + +
nametyperequired?description
idstringyesUnique identifier assigned to each created batch change.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The batch change is returned in response body.
403Forbidden - The user does not have the access required to perform the action.
404Not Found - Batch change not found.
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
userIdstringThe unique identifier of the user that created the batch change.
userNamestringThe username of the user that created the batch change.
commentsstringOptional comments about the batch change.
createdTimestampdate-timeThe timestamp (UTC) when the batch change was created.
changesArray of SingleChangeArray of single changes within a batch change. A SingleChange can either be a SingleAddChange or a SingleDeleteRRSetChange.
statusBatchChangeStatusStatus of the batch change.
idstringThe unique identifier for this batch change.
scheduledTimedate-timeOptional requested date and time to process the batch change.
approvalStatusBatchChangeApprovalStatusApproval status of the batch change.
reviewerIdstringOptional identifier of reviewer if batch change required manual review
reviewCommentstringOptional comment by reviewer if batch change required manual review
reviewTimestampdate-timeOptional timestamp (UTC) when the batch change was reviewed if manual review was required.
cancelledTimestampdate-timeOptional timestamp (UTC) if the batch change was cancelled by the creator
+ +

EXAMPLE RESPONSE

+ +
{
+    "userId": "vinyl", 
+    "userName": "vinyl201", 
+    "comments": "this is optional", 
+    "createdTimestamp": "2018-05-09T14:19:34Z", 
+    "changes": [
+        {
+            "changeType": "Add", 
+            "inputName": "parent.com.", 
+            "type": "A", 
+            "ttl": 200, 
+            "record": {
+                "address": "4.5.6.7"
+            }, 
+            "status": "Pending", 
+            "recordName": "parent.com.", 
+            "zoneName": "parent.com.", 
+            "zoneId": "74e93bfc-7296-4b86-83d3-1ffcb0eb3d13",
+            "recordChangeId": "a07299ce-5f81-11e8-9c2d-fa7ae01bbebc",
+            "recordSetId": "a0729f00-5f81-11e8-9c2d-fa7ae01bbebc",
+            "id": "7573ca11-3e30-45a8-9ba5-791f7d6ae7a7"
+        },
+        {
+            "changeType": "DeleteRecordSet", 
+            "inputName": "deleting.parent.com.", 
+            "type": "CNAME", 
+            "status": "Pending", 
+            "recordName": "deleting", 
+            "zoneName": "parent.com.", 
+            "zoneId": "74e93bfc-7296-4b86-83d3-1ffcb0eb3d13",
+            "recordChangeId": "bed15986-5f82-11e8-9c2d-fa7ae01bbebc",
+            "recordSetId": "c089e52c-5f82-11e8-9c2d-fa7ae01bbebc",
+            "id": "7573ca11-3e30-45a8-9ba5-791f7d6ae7a7"
+        }
+    ], 
+    "status": "PendingProcessing",
+    "id": "02bd95f4-a32c-443b-82eb-54dbaa55b31a"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/get-group.html b/api/get-group.html new file mode 100644 index 000000000..8c01cd4b1 --- /dev/null +++ b/api/get-group.html @@ -0,0 +1,130 @@ +VinylDNS: Get Group

Get Group

+ +

Gets a group that you are a part of

+ +

HTTP REQUEST

+ +
+

GET /groups/{groupId}

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The group is returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
404Not Found - The group was not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
idstringUnique UUID of the group
namemapThe name of the group
emailstringThe email distribution list of the group
descriptionstringThe group description, the group may not have this field if it was not set
createdstringThe timestamp (UTC) the group was created
statusstringActive or Deleted
membersArray of User Id objectsIds of members of the group including admins
adminsArray of User Id objectsIds of admins of the group
+ +

EXAMPLE RESPONSE

+ +
{
+  "id": "6f8afcda-7529-4cad-9f2d-76903f4b1aca",
+  "name": "some-group",
+  "email": "test@example.com",
+  "created": "2017-03-02T15:29:21Z",
+  "status": "Active",
+  "members": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    },
+    {
+      "id": "c8630ebc-0af2-4c9a-a0a0-d18c590ed03e"
+    }
+  ],
+  "admins": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    }
+  ]
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/get-recordset-change.html b/api/get-recordset-change.html new file mode 100644 index 000000000..b820aca88 --- /dev/null +++ b/api/get-recordset-change.html @@ -0,0 +1,153 @@ +VinylDNS: Get RecordSet Change

Get RecordSet Change

+ +

RecordSet changes (Create, Update, Delete) are not immediately applied to the DNS backend; they are queued up for processing. Most changes are applied within a few seconds. +When you submit a change for processing, the response is a Change model. You can use the information in that change model in order to poll for the status of the change until it completes (status = Complete) or fails (status = Failed)

+ +

HTTP REQUEST

+ +
+

GET /zones/{zoneId}/recordsets/{recordSetId}/changes/{recordChangeId}

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The record set change is returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - The zone, record set, or change was not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zonemapContains information about the zone when the change was created
recordSetmapContains the recordset model
userIdstringThe user ID that initiated the change
changeTypestringType of change requested (Create, Update, or Delete)
createdstringThe timestamp (UTC) the change was initiated
idstringThe ID of the change. This is not the ID of the recordset
statusRecordSetChangeStatusThe status of the change (Pending, Complete, or Failed)
singleBatchChangeIdsarray of SingleBatchChange ID objectsIf the recordset change was part of a batch change, the IDs of the single changes that comprise the recordset change
+ +

EXAMPLE RESPONSE

+ +
{
+  "zone": {
+    "name": "vinyl.",
+    "email": "test@test.com",
+    "status": "Active",
+    "created": "2017-02-23T14:52:44Z",
+    "id": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "shared": false,
+    "acl": {
+      "rules": [
+
+      ]
+    },
+    "adminGroupId": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae"
+  },
+  "recordSet": {
+    "type": "A",
+    "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "name": "foo",
+    "ttl": 300,
+    "status": "Pending",
+    "created": "2017-02-23T14:58:54Z",
+    "records": [
+      {
+        "address": "10.10.10.10"
+      }
+    ],
+    "id": "9a41b99c-8e67-445f-bcf3-f9c7cd1f2357",
+    "account": "0215d410-9b7e-4636-89fd-b6b948a06347"
+  },
+  "userId": "0215d410-9b7e-4636-89fd-b6b948a06347",
+  "changeType": "Create",
+  "status": "Pending",
+  "created": "2017-02-23T14:58:54Z",
+  "id": "fef81f0b-f439-462d-88df-c773d3686c9b",
+  "singleBatchChangeIds": []
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/get-recordset.html b/api/get-recordset.html new file mode 100644 index 000000000..e0688386e --- /dev/null +++ b/api/get-recordset.html @@ -0,0 +1,159 @@ +VinylDNS: Get RecordSet

Get RecordSet

+ +

Gets a RecordSet in a specified zone

+ +

HTTP REQUEST

+ +
+

GET /zones/{zoneId}/recordsets/{recordSetId}

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The record set is returned
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - The zone with the id specified was not found, or the record set with id was not found
+ +

HTTP RESPONSE ATTRIBUTES

+

The returned json object has all the fields from the RecordSet as well as an added accessLevel field

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
typestringType of record set
zoneIdstringThe zone the record is stored in
namestringThe name of the record set
ttlintegerThe TTL of the record set in seconds
statusstringThe status of the record set
createdstringThe timestamp (UTC) the change was initiated
updatedstringThe timestamp (UTC) the change was last updated
recordsarray of record dataArray of record data objects
idstringThe unique ID of the record set
accountstringDEPRECATED the ID of the account that created the record set
accessLevelstringaccessLevel that user has to record set based off acl rules and whether or not user is in Zone Admin Group
ownerGroupIdstringRecord ownership assignment, if found, applicable if the recordset is in a shared zone
ownerGroupNamestringName of assigned owner group, if found
+ +

EXAMPLE RESPONSE

+ +
{
+  "type": "A",
+  "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+  "name": "already-exists",
+  "ttl": 38400,
+  "status": "Active",
+  "created": "2017-02-23T15:12:41Z",
+  "updated": "2017-02-23T15:12:41Z",
+  "records": [
+    {
+      "address": "6.6.6.1"
+    }
+  ],
+  "id": "dd9c1120-0594-4e61-982e-8ddcbc8b2d21",
+  "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+  "accessLevel": "Delete",
+  "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe",
+  "ownerGroupName": "Shared Group"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/get-zone-by-id.html b/api/get-zone-by-id.html new file mode 100644 index 000000000..10b96cad9 --- /dev/null +++ b/api/get-zone-by-id.html @@ -0,0 +1,107 @@ +VinylDNS: Get Zone by ID

Get Zone by ID

+ +

Retrieves a zone with the matching zone ID

+ +

HTTP REQUEST

+ +
+

GET /zones/{zoneId}

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - Successful lookup, the zone is returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - Zone not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + +
nametypedescription
zonemaprefer to zone model
+ +

EXAMPLE RESPONSE

+ +
{
+  "zone": {
+    "status": "Active",
+    "account": "6baa85ad-267f-44ff-b535-818b7d7a2467",
+    "name": "system-test.",
+    "created": "2016-12-28T18:12:09Z",
+    "adminGroupId": "6baa85ad-267f-44ff-b535-818b7d7a2467",
+    "email": "test@example.com",
+    "connection": {
+      "primaryServer": "127.0.0.1:5301",
+      "keyName": "vinyl.",
+      "name": "system-test.",
+      "key": "OBF:1:B2cetOaRf1YAABAAek/w22XyKAleCRjA/hZO9fkNtNufPIRWTYHXviAk9GjrfcFOG9nNuB=="
+    },
+    "transferConnection": {
+      "primaryServer": "127.0.0.1:5301",
+      "keyName": "vinyl.",
+      "name": "system-test.",
+      "key": "OBF:1:PNt2k1nYkC0AABAAePpNMrDp+4C4GDbicWWlAqB5c4mKoKhvfpiWY1PfuRCVzSAeXydztB=="
+    },
+    "shared": true,
+    "acl": {
+      "rules": []
+    },
+    "id": "0f2fcece-b4ee-4982-b671-e5946f7db81d",
+    "latestSync": "2016-12-16T15:27:26Z"
+  }
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/get-zone-by-name.html b/api/get-zone-by-name.html new file mode 100644 index 000000000..1ccec5fb3 --- /dev/null +++ b/api/get-zone-by-name.html @@ -0,0 +1,107 @@ +VinylDNS: Get Zone by Name

Get Zone by Name

+ +

Retrieves a zone with the matching zone name

+ +

HTTP REQUEST

+ +
+

GET /zones/name/{zoneName}

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - Successful lookup, the zone is returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - Zone not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + +
nametypedescription
zonemaprefer to zone model
+ +

EXAMPLE RESPONSE

+ +
{
+  "zone": {
+    "status": "Active",
+    "account": "6baa85ad-267f-44ff-b535-818b7d7a2467",
+    "name": "system-test.",
+    "created": "2016-12-28T18:12:09Z",
+    "adminGroupId": "6baa85ad-267f-44ff-b535-818b7d7a2467",
+    "email": "test@example.com",
+    "connection": {
+      "primaryServer": "127.0.0.1:5301",
+      "keyName": "vinyl.",
+      "name": "system-test.",
+      "key": "OBF:1:B2cetOaRf1YAABAAek/w22XyKAleCRjA/hZO9fkNtNufPIRWTYHXviAk9GjrfcFOG9nNuB=="
+    },
+    "transferConnection": {
+      "primaryServer": "127.0.0.1:5301",
+      "keyName": "vinyl.",
+      "name": "system-test.",
+      "key": "OBF:1:PNt2k1nYkC0AABAAePpNMrDp+4C4GDbicWWlAqB5c4mKoKhvfpiWY1PfuRCVzSAeXydztB=="
+    },
+    "shared": true,
+    "acl": {
+      "rules": []
+    },
+    "id": "0f2fcece-b4ee-4982-b671-e5946f7db81d",
+    "latestSync": "2016-12-16T15:27:26Z"
+  }
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/index.html b/api/index.html new file mode 100644 index 000000000..0c294f84d --- /dev/null +++ b/api/index.html @@ -0,0 +1,27 @@ +VinylDNS: API documentation

API documentation

+ + +
Improve this page
\ No newline at end of file diff --git a/api/list-batchchanges.html b/api/list-batchchanges.html new file mode 100644 index 000000000..a596cb395 --- /dev/null +++ b/api/list-batchchanges.html @@ -0,0 +1,241 @@ +VinylDNS: List Batch Changes

List Batch Changes

+ +

Retrieves the most recent 100 batch changes created by the user. This call will return a subset of the full information in each change, as detailed in the attributes section.

+ +

The max number of batch changes that are returned from a single request has been set to 100.

+ +

HTTP REQUEST

+ +
+

GET zones/batchrecordchanges?startFrom={response.nextId}&maxItems={1-100}&ignoreAccess={true | false}&approval_status={BatchChangeApprovalStatus}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
startFromintnoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results.
maxItemsintnoThe number of items to return in the page. Valid values are 1 - 100. Defaults to 100 if not provided.
ignoreAccessbooleannoFlag determining whether to retrieve only batch changes made by calling user or to retrieve all changes. Only affects system administrators (ie. support and super users). Defaults to false if not provided.
approvalStatusBatchChangeApprovalStatusnoFilter batch changes based on approval status. Can be one of AutoApproved, PendingReview, ManuallyApproved, Rejected, or Cancelled.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + +
Codedescription
200OK - the batch change is returned in response body.
403Forbidden - the user does not have the access required to perform the action.
+ +

If there are no batch changes created by the user, a successful empty response body is returned.

+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
batchChangesArray of BatchChangeSummarySummary information for the most recent 100 batch changes created by the user.
startFromintstartFrom sent in request, will not be returned if not provided.
nextIdintstartFrom parameter of next page request, will not be returned if record sets are exhausted.
maxItemsintegermaxItems sent in request, default is 100.
ignoreAccessbooleanignoreAccess sent in request, default is false.
approvalStatusBatchChangeApprovalStatusapprovalStatus sent in request, will not be returned if not provided.
+ +
BatchChangeSummary
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
userIdstringThe unique identifier of the user that created the batch change.
userNamestringThe username of the user that created the batch change.
commentsstringConditional: comments about the batch change, if provided.
createdTimestampdate-timeThe timestamp (UTC) when the batch change was created.
totalChangesintThe total number of single changes within the batch change.
statusBatchChangeStatusStatus of the batch change.
idstringThe unique identifier for this batch change.
ownerGroupNamestringConditional: Record ownership assignment, if provided.
approvalStatusBatchChangeApprovalStatusWhether the batch change is currently awaiting manual review. Can be one of AutoApproved, PendingReview, ManuallyApproved, Rejected, or Cancelled.
+ +

EXAMPLE RESPONSE

+ +
{
+    "batchChanges": [
+        {
+            "userId": "vinyl", 
+            "userName": "vinyl201", 
+            "comments": "this is optional", 
+            "createdTimestamp": "2018-05-11T18:12:13Z", 
+            "totalChanges": 5, 
+            "status": "Complete", 
+            "id": "bd03175c-6fd7-419e-991c-3d5d1441d995",
+            "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe",
+            "ownerGroupName": "some owner group name",
+            "approvalStatus": "AutoApproved"
+        }, 
+        {
+            "userId": "vinyl", 
+            "userName": "vinyl201", 
+            "comments": "this is optional", 
+            "createdTimestamp": "2018-05-11T18:12:12Z", 
+            "totalChanges": 10, 
+            "status": "Complete",
+            "id": "743cbd16-5440-4cf7-bca9-20319df9b651",
+            "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe",
+            "ownerGroupName": "some owner group name",
+            "approvalStatus": "ManuallyApproved"
+        },
+        {
+            "userId": "vinyl", 
+            "userName": "vinyl201", 
+            "comments": "this is optional", 
+            "createdTimestamp": "2018-05-11T18:12:12Z", 
+            "totalChanges": 7, 
+            "status": "Complete", 
+            "id": "2b827a33-7c4f-4623-8dd9-277c6fba0e54",
+            "approvalStatus": "Rejected",
+            "reviewerId": "270ba4b3-f5eb-4043-a283-1a6cec0993f3",
+            "reviewerName": "some reviewer",
+            "reviewTimestamp": "2018-05-13T13:12:10Z"
+        }
+    ],
+    "maxItems": 100,
+    "ignoreAccess": false
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-group-activity.html b/api/list-group-activity.html new file mode 100644 index 000000000..7956cf2a0 --- /dev/null +++ b/api/list-group-activity.html @@ -0,0 +1,207 @@ +VinylDNS: List Group Activity

List Group Activity

+ +

Retrieves a list of group activity

+ +

HTTP REQUEST

+ +
+

GET /groups/{groupId}/activity?startFrom={response.nextId}&maxItems={1 - 100}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
startFromanynoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results
maxItemsintegernoThe number of items to return in the page. Valid values are 1 to 100. Defaults to 100 if not provided.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The changes have been returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
404Not Found - The group was not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
changesArray of Group Changesrefer to Group Change
startFromanystartFrom sent in request, will not be returned if not provided
nextIdanynextId, used as startFrom parameter of next page request, will not be returned if activity is exhausted
maxItemsintegermaxItems sent in request, default is 100
+ +

GROUP CHANGE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
newGroupmapThe new group as a result of the change, refer to Membership Model
oldGroupmapThe old group before the change, refer to Membership Model
createdstringMillisecond timestamp that change was created
userIdstringUser Id of user who made the change
changeTypestringThe type change, either Create, Update, or Delete
+ +

EXAMPLE RESPONSE

+ +
{
+  "maxItems": 100,
+  "changes": [
+    {
+      "newGroup": {
+        "status": "Active",
+        "name": "test-list-group-activity-max-item-success",
+        "created": "2017-03-02T18:49:58Z",
+        "id": "1555bac7-0343-4d11-800f-955afb481818",
+        "admins": [
+          {
+            "id": "ok"
+          }
+        ],
+        "members": [
+          {
+            "id": "dummy199"
+          },
+          {
+            "id": "ok"
+          }
+        ],
+        "email": "test@test.com"
+      },
+      "created": "1488480605378",
+      "userId": "some-user",
+      "changeType": "Update",
+      "oldGroup": {
+        "status": "Active",
+        "name": "test-list-group-activity-max-item-success",
+        "created": "2017-03-02T18:49:58Z",
+        "id": "1555bac7-0343-4d11-800f-955afb481818",
+        "admins": [
+          {
+            "id": "ok"
+          }
+        ],
+        "members": [
+          {
+            "id": "dummy198"
+          },
+          {
+            "id": "ok"
+          }
+        ],
+        "email": "test@test.com"
+      },
+      "id": "11abb88b-c47d-469b-bc2d-6656e00711cf"
+    }
+  ]
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-group-admins.html b/api/list-group-admins.html new file mode 100644 index 000000000..4f8fed8f4 --- /dev/null +++ b/api/list-group-admins.html @@ -0,0 +1,95 @@ +VinylDNS: List Group Admins

List Group Admins

+ +

Retrieves a group’s admins

+ +

HTTP REQUEST

+ +
+

GET /groups/{groupId}/admins

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The admins have been returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
404Not Found - The group was not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + +
nametypedescription
adminsArray of Usersrefer to membership model
+ +

EXAMPLE RESPONSE

+ +
{
+  "admins": [
+    {
+      "userName": "jdoe201",
+      "firstName": "john",
+      "created": "2017-03-02T16:39:02Z",
+      "lastName": "doe",
+      "email": "john_doe@example.com",
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    },
+    {
+      "userName": "jdoe202",
+      "firstName": "jane",
+      "created": "2017-03-02T16:50:02Z",
+      "lastName": "doe",
+      "email": "jane_doe@example.com",
+      "id": "1764183c-5e75-4ae6-8833-503cd5f4dcb4"
+    }
+  ]
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-group-members.html b/api/list-group-members.html new file mode 100644 index 000000000..477b07d40 --- /dev/null +++ b/api/list-group-members.html @@ -0,0 +1,140 @@ +VinylDNS: List Group Members

List Group Members

+ +

Retrieves a list of group members

+ +

HTTP REQUEST

+ +
+

GET /groups/{groupId}/members?startFrom={response.nextId}&maxItems={1 - 100}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
startFromanynoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results
maxItemsintegernoThe number of items to return in the page. Valid values are 1 to 100. Defaults to 100 if not provided.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The members have been returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
404Not Found - The group was not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
membersArray of Usersrefer to membership model, these Users will also include an isAdmin attribute
startFromanystartFrom sent in request, will not be returned if not provided
nextIdanynextId, used as startFrom parameter of next page request, will not be returned if members are exhausted
maxItemsintegermaxItems sent in request, default is 100
+ +

EXAMPLE RESPONSE

+ +
{
+  "members": [
+    {
+      "id": "0b1acc37-7d97-4da7-8a28-f1770bb99643",
+      "userName": "jdoe201",
+      "firstName": "John",
+      "lastName": "Doe",
+      "email": "John_Doe@example.com",
+      "created": "2017-03-02T18:42:31Z",
+      "isAdmin": true
+    },
+    {
+      "id": "0cb85121-671a-4920-ab02-0c17a7b40874",
+      "userName": "bwayne300",
+      "firstName": "Bruce",
+      "lastName": "Wayne",
+      "email": "Bruce_Wayne@cable.example.com",
+      "created": "2017-03-02T18:42:54Z",
+      "isAdmin": false
+    }
+  ],
+  "maxItems": 100
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-groups.html b/api/list-groups.html new file mode 100644 index 000000000..1957e6fe2 --- /dev/null +++ b/api/list-groups.html @@ -0,0 +1,175 @@ +VinylDNS: List Groups

List Groups

+ +

Retrieves a list of groups that you are a part of

+ +

HTTP REQUEST

+ +
+

GET /groups?startFrom={response.nextId}&maxItems={1 - 100}&groupNameFilter={filter}&ignoreAccess={true | false}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
groupNameFilterstringnoOne or more characters contained in the name of the group set to search for. For example TP. This is a contains search only, no wildcards or regular expressions are supported
startFromanynoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results
maxItemsintegernoThe number of items to return in the page. Valid values are 1 to 100. Defaults to 100 if not provided.
ignoreAccessbooleannoIf false, returns only groups the requesting user is a member of. If true, returns groups in the system, regardless of membership. Defaults to false if not provided. Super and support admin see all groups regardless of this value.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The groups have been returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
groupsArray of Groupsrefer to membership model
groupNameFilterstringname filter sent in request
startFromanystartFrom sent in request, will not be returned if not provided
nextIdanynextId, used as startFrom parameter of next page request, will not be returned if groups are exhausted
maxItemsintegermaxItems sent in request, default is 100
ignoreAccessbooleanThe ignoreAccess parameter that was sent in the HTTP request. This will be false if not sent.
+ +

EXAMPLE RESPONSE

+ +
{
+  "maxItems": 100,
+  "groups": [
+    {
+      "id": "93887728-2b26-4749-ba69-98871dda9cc0",
+      "name": "some-other-group",
+      "email": "test@example.com",
+      "created": "2017-03-02T16:23:07Z",
+      "status": "Active",
+      "members": [
+        {
+          "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+        }
+      ],
+      "admins": [
+        {
+          "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+        }
+      ]
+    },
+    {
+      "id": "aa1ea217-70a7-4350-b22b-c7e2f2158fb9",
+      "name": "some-group",
+      "email": "test@example.com",
+      "created": "2017-03-02T16:22:57Z",
+      "status": "Active",
+      "members": [
+        {
+          "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+        }
+      ],
+      "admins": [
+        {
+          "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+        }
+      ]
+    }
+  ],
+  "ignoreAccess": false
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-recordset-changes.html b/api/list-recordset-changes.html new file mode 100644 index 000000000..6db062628 --- /dev/null +++ b/api/list-recordset-changes.html @@ -0,0 +1,610 @@ +VinylDNS: List RecordSet Changes

List RecordSet Changes

+ +

RecordSet changes (Create, Update, Delete) are not immediately applied to the DNS backend; they are queued up for processing. Most changes are applied within a few seconds. +When you submit a change for processing, the response is a Change model. You can use the information in that change model in order to poll for the status of the change until it completes (status = Complete) or fails (status = Failed) +

+Retrieves a list of RecordSet changes in a zone. All RecordSet changes are stored, including those coming from zone syncs. RecordSet changes come in max page sizes of 100 changes, paging must be done independently using startFrom and nextId parameters

+ +

HTTP REQUEST

+ +
+

GET /zones/{zoneId}/recordsetchanges?startFrom={response.nextId}&maxItems={1 - 100}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
startFromanynoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results
maxItemsintnoThe number of items to return in the page. Valid values are 1 - 100. Defaults to 100 if not provided.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - the recordset changes are returned in response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - Zone not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zoneIdstringId of zone used for request
recordSetChangesarray of recordset changesarray of recordset changes sorted by created time in descending order
startFromany(optional) The startFrom parameter that was sent in on the HTTP request. Will not be present if the startFrom parameter was not sent
nextIdany(optional) The identifier to be passed in as the startFrom parameter to retrieve the next page of results. If there are no results left, this field will not be present
maxItemsintThe maxItems parameter that was sent in on the HTTP request. This will be 100 if not sent
statusstringThe status of the change (Pending, Complete, Failed)
+ +

EXAMPLE RESPONSE

+ +
{
+  "recordSetChanges": [
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:58Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:58Z",
+          "name": "test-create-cname-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "cname": "changed-cname."
+            }
+          ],
+          "ttl": 200,
+          "type": "CNAME",
+          "id": "f62235df-5372-443c-9ba4-bdd3fca452f4"
+        },
+        "changeType": "Delete",
+        "userId": "history-id",
+        "updates": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:58Z",
+          "name": "test-create-cname-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "cname": "changed-cname."
+            }
+          ],
+          "ttl": 200,
+          "type": "CNAME",
+          "id": "f62235df-5372-443c-9ba4-bdd3fca452f4"
+        },
+        "id": "68fd6dbe-0da8-4280-bcf3-37f54528dc41"
+      },
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:58Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:58Z",
+          "name": "test-create-aaaa-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "2003:db8:0:0:0:0:0:4"
+            },
+            {
+              "address": "2002:db8:0:0:0:0:0:3"
+            }
+          ],
+          "ttl": 200,
+          "type": "AAAA",
+          "id": "9559103d-4cb4-4d34-9d3f-eab3fe2e8aed"
+        },
+        "changeType": "Delete",
+        "userId": "history-id",
+        "updates": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-aaaa-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "2003:db8:0:0:0:0:0:4"
+            },
+            {
+              "address": "2002:db8:0:0:0:0:0:3"
+            }
+          ],
+          "ttl": 200,
+          "type": "AAAA",
+          "id": "9559103d-4cb4-4d34-9d3f-eab3fe2e8aed"
+        },
+        "id": "dabf1e57-49e7-4d2d-8a00-814d88546b0c"
+      },
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:58Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:58Z",
+          "name": "test-create-a-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "9.9.9.9"
+            },
+            {
+              "address": "10.2.2.2"
+            }
+          ],
+          "ttl": 200,
+          "type": "A",
+          "id": "f1fd620e-5ff3-4ee9-839f-bc747a9867d9"
+        },
+        "changeType": "Delete",
+        "userId": "history-id",
+        "updates": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-a-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "9.9.9.9"
+            },
+            {
+              "address": "10.2.2.2"
+            }
+          ],
+          "ttl": 200,
+          "type": "A",
+          "id": "f1fd620e-5ff3-4ee9-839f-bc747a9867d9"
+        },
+        "id": "23ae1487-bc7f-481b-a544-10ceb7a87540"
+      },
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:57Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:58Z",
+          "name": "test-create-cname-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "cname": "changed-cname."
+            }
+          ],
+          "ttl": 200,
+          "type": "CNAME",
+          "id": "f62235df-5372-443c-9ba4-bdd3fca452f4"
+        },
+        "changeType": "Update",
+        "userId": "history-id",
+        "updates": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-cname-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "cname": "cname."
+            }
+          ],
+          "ttl": 100,
+          "type": "CNAME",
+          "id": "f62235df-5372-443c-9ba4-bdd3fca452f4"
+        },
+        "id": "5c722555-c7be-4620-a1fd-8ca53a5b8683"
+      },
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:57Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-aaaa-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "2003:db8:0:0:0:0:0:4"
+            },
+            {
+              "address": "2002:db8:0:0:0:0:0:3"
+            }
+          ],
+          "ttl": 200,
+          "type": "AAAA",
+          "id": "9559103d-4cb4-4d34-9d3f-eab3fe2e8aed"
+        },
+        "changeType": "Update",
+        "userId": "history-id",
+        "updates": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-aaaa-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "2001:db8:0:0:0:0:0:3"
+            },
+            {
+              "address": "2002:db8:0:0:0:0:0:3"
+            }
+          ],
+          "ttl": 100,
+          "type": "AAAA",
+          "id": "9559103d-4cb4-4d34-9d3f-eab3fe2e8aed"
+        },
+        "id": "480fff34-61d3-4a1d-9696-f5007842b38a"
+      },
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:57Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-a-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "9.9.9.9"
+            },
+            {
+              "address": "10.2.2.2"
+            }
+          ],
+          "ttl": 200,
+          "type": "A",
+          "id": "f1fd620e-5ff3-4ee9-839f-bc747a9867d9"
+        },
+        "changeType": "Update",
+        "userId": "history-id",
+        "updates": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-a-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "10.1.1.1"
+            },
+            {
+              "address": "10.2.2.2"
+            }
+          ],
+          "ttl": 100,
+          "type": "A",
+          "id": "f1fd620e-5ff3-4ee9-839f-bc747a9867d9"
+        },
+        "id": "999d8674-e59b-478e-95c0-9d4eb964f2be"
+      },
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "connection": {
+            "primaryServer": "127.0.0.1:5301",
+            "keyName": "vinyl.",
+            "name": "system-test-history.",
+            "key": "OBF:1:YVgGogd/Y+oAABAAIp4s3z7FAn92uvfOci9v0jMjihQ+uV3bOCyNwpMPh78tL4q/A8dR7A=="
+          },
+          "transferConnection": {
+            "primaryServer": "127.0.0.1:5301",
+            "keyName": "vinyl.",
+            "name": "system-test-history.",
+            "key": "OBF:1:Pq3UqxiceV4AABAAdu90et1pkNn2ZO3MuYstki5BkQVm3T50RQLarpVhIgaoOKLi2CdL6Q=="
+          },
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:57Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-cname-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "cname": "cname."
+            }
+          ],
+          "ttl": 100,
+          "type": "CNAME",
+          "id": "f62235df-5372-443c-9ba4-bdd3fca452f4"
+        },
+        "changeType": "Create",
+        "userId": "history-id",
+        "id": "b05f0837-84bd-47aa-8a95-7bde91046268"
+      },
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:57Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-aaaa-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "2001:db8:0:0:0:0:0:3"
+            },
+            {
+              "address": "2002:db8:0:0:0:0:0:3"
+            }
+          ],
+          "ttl": 100,
+          "type": "AAAA",
+          "id": "9559103d-4cb4-4d34-9d3f-eab3fe2e8aed"
+        },
+        "changeType": "Create",
+        "userId": "history-id",
+        "id": "e7e6b7f9-5253-4947-9580-3f0b81a48717"
+      },
+      {
+        "status": "Complete",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:57Z",
+        "recordSet": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "test-create-a-ok",
+          "created": "2016-12-30T15:37:57Z",
+          "account": "history-id",
+          "zoneId": "9f353bc7-cb8d-491c-b074-34afafc97c5f",
+          "records": [
+            {
+              "address": "10.1.1.1"
+            },
+            {
+              "address": "10.2.2.2"
+            }
+          ],
+          "ttl": 100,
+          "type": "A",
+          "id": "f1fd620e-5ff3-4ee9-839f-bc747a9867d9"
+        },
+        "changeType": "Create",
+        "userId": "history-id",
+        "id": "6743d428-7748-4348-a6c9-ae59e9eeaf97"
+      }
+    ],
+  "maxItems": 100
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-recordsets-by-zone.html b/api/list-recordsets-by-zone.html new file mode 100644 index 000000000..280f8744e --- /dev/null +++ b/api/list-recordsets-by-zone.html @@ -0,0 +1,266 @@ +VinylDNS: List / Search RecordSets

List / Search RecordSets by Zone

+ +

Retrieves a list of RecordSets from the zone

+ +

HTTP REQUEST

+ +
+

GET /zones/{zoneId}/recordsets?startFrom={response.nextId}&maxItems={1 - 100}&recordNameFilter={filter}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
recordNameFilterstringnoCharacters that are part of the record name to search for. The wildcard character * is supported, for example www*. Omit the wildcard when searching for an exact record name.
recordTypeFilterArray of RecordTypenoAn array of record types to filter for listing record sets. Refer to recordset mode for supported types. Invalid record types will be ignored. If left empty or no valid record types are provided, then all record types will be returned.
nameSortstringnoName sort order for record sets returned by list record set response. Valid values are ASC (ascending; default) and DESC (descending).
startFromanynoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results
maxItemsintegernoThe number of items to return in the page. Valid values are 1 to 100. Defaults to 100 if not provided.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The record sets are returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - Zone or RecordSet not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
recordSetsArray of RecordSetsrefer to recordset model, the RecordSet data will also include the accessLevel the requesting user has based off acl rules and membership in Zone Admin Group
startFromanystartFrom sent in request, will not be returned if not provided
nextIdanynextId, used as startFrom parameter of next page request, will not be returned if record sets are exhausted
maxItemsintegermaxItems sent in request, default is 100
recordNameFilterstringname filter sent in request
recordTypeFilterArray of RecordTyperecord type filter sent in request
nameSortstringname sort order sent in request
+ +

EXAMPLE RESPONSE

+ +
{
+  "recordSets": [
+    {
+      "type": "A",
+      "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+      "name": "already-exists",
+      "ttl": 38400,
+      "status": "Active",
+      "created": "2017-02-23T15:12:41Z",
+      "updated": "2017-02-23T15:12:41Z",
+      "records": [
+        {
+          "address": "6.6.6.1"
+        }
+      ],
+      "id": "dd9c1120-0594-4e61-982e-8ddcbc8b2d21",
+      "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+      "accessLevel": "Delete"
+    },
+    {
+      "type": "NS",
+      "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+      "name": "vinyl",
+      "ttl": 38400,
+      "status": "Active",
+      "created": "2017-02-23T15:12:33Z",
+      "records": [
+        {
+          "nsdname": "172.17.42.2."
+        }
+      ],
+      "id": "daf5ea7b-c28c-422a-ba47-2c37ca567a77",
+      "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+      "accessLevel": "Delete"
+    },
+    {
+      "type": "SOA",
+      "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+      "name": "vinyl",
+      "ttl": 38400,
+      "status": "Active",
+      "created": "2017-02-23T15:12:33Z",
+      "records": [
+        {
+          "mname": "172.17.42.2.",
+          "rname": "admin.test.com.",
+          "serial": 1439234395,
+          "refresh": 10800,
+          "retry": 3600,
+          "expire": 604800,
+          "minimum": 38400
+        }
+      ],
+      "id": "9da83158-05ab-4f14-8bd0-0a4d85cdeb30",
+      "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+      "accessLevel": "Delete"
+    },
+    {
+      "type": "A",
+      "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+      "name": "vinyl",
+      "ttl": 38400,
+      "status": "Active",
+      "created": "2017-02-23T15:12:33Z",
+      "records": [
+        {
+          "address": "5.5.5.5"
+        }
+      ],
+      "id": "d73275ff-e71e-4024-aef1-1236741443b5",
+      "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+      "accessLevel": "Delete"
+    },
+    {
+      "type": "A",
+      "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+      "name": "jenkins",
+      "ttl": 38400,
+      "status": "Active",
+      "created": "2017-02-23T15:12:33Z",
+      "records": [
+        {
+          "address": "10.1.1.1"
+        }
+      ],
+      "id": "0432f63b-3947-4262-9ade-a3311d07a099",
+      "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+      "accessLevel": "Delete"
+    },
+    {
+      "type": "A",
+      "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+      "name": "test",
+      "ttl": 38400,
+      "status": "Active",
+      "created": "2017-02-23T15:12:33Z",
+      "records": [
+        {
+          "address": "4.4.4.4"
+        },
+        {
+          "address": "3.3.3.3"
+        }
+      ],
+      "id": "dc0e3ce9-ec01-47f1-9418-461dc1754f48",
+      "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+      "accessLevel": "Delete"
+    }
+  ],
+  "maxItems": 100,
+  "nameSort": "ASC"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-recordsets-global.html b/api/list-recordsets-global.html new file mode 100644 index 000000000..4068fa735 --- /dev/null +++ b/api/list-recordsets-global.html @@ -0,0 +1,185 @@ +VinylDNS: Global List / Search RecordSets

Global List / Search RecordSets

+ +

Retrieves a list of RecordSets globally in the VinylDNS database based on search criteria. A minimum of two alpha-numeric characters is required.

+ +

HTTP REQUEST

+ +
+

GET /recordsets?startFrom={response.nextId}&maxItems={1 - 100}&recordNameFilter={recordNameFilter}&recordTypeFilter={recordTypeFilter}&recordOwnerGroupFilter={recordOwnerGroupFilter}&nameSort={nameSort}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
recordNameFilterstringyesCharacters that are part of the record name to search for. The wildcard character * is supported, for example www*. Omit the wildcard when searching for an exact record name. At least two alphanumeric characters are required for searching.
recordTypeFilterArray of RecordTypenoAn array of record types to filter for listing record sets. Refer to recordset mode for supported types. Invalid record types will be ignored. If left empty or no valid record types are provided, then all record types will be returned.
recordOwnerGroupFilterstringnoOwner group ID for record set.
nameSortstringnoName sort order for record sets returned by list record set response. Valid values are ASC (ascending; default) and DESC (descending).
startFromanynoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results
maxItemsintegernoThe number of items to return in the page. Valid values are 1 to 100. Defaults to 100 if not provided.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The record sets are returned in the response body
422Unprocessable Entity - recordNameFilter was either omitted or provided but does not contain at least two alphanumeric characters
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
recordSetsArray of RecordSetsrefer to recordset model
startFromanystartFrom sent in request, will not be returned if not provided
nextIdanynextId, used as startFrom parameter of next page request, will not be returned if record sets are exhausted
maxItemsintegermaxItems sent in request, default is 100
recordNameFilterstringname filter sent in request
recordTypeFilterArray of RecordTyperecord type filter sent in request
recordOwnerGroupFilterstringrecord owner group sent in request
nameSortstringname sort order sent in request
+ +

EXAMPLE RESPONSE

+ +
{
+  "recordSets": [
+    {
+      "type": "A",
+      "zoneId": "5f5304ba-c81f-456c-9d33-bb6179c8b1f1",
+      "name": "foo",
+      "ttl": 7200,
+      "status": "Active",
+      "created": "2019-04-26T17:15:35Z",
+      "records": [
+        {
+          "address": "1.1.1.1"
+        }
+      ],
+      "id": "f802596f-4f0e-4e65-bb43-c7ca439d2608",
+      "account": "system",
+      "fqdn": "foo.example.com.",
+      "zoneName": "example.com.",
+      "zoneShared": true
+    }
+  ],
+  "maxItems": 100,
+  "recordNameFilter": "foo*",
+  "recordTypeFilter": [
+    "A"
+  ],
+  "nameSort": "ASC"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-zone-changes.html b/api/list-zone-changes.html new file mode 100644 index 000000000..66e48f5f3 --- /dev/null +++ b/api/list-zone-changes.html @@ -0,0 +1,176 @@ +VinylDNS: List Zone Changes

List Zone Changes

+ +

Retrieves a list of zone changes to a zone. All zone changes are stored, including those coming from zone syncs. Zone changes come in max page sizes of 100 changes, paging must be done independently using startFrom and nextId parameters

+ +

HTTP REQUEST

+ +
+

GET /zones/{zoneId}/changes?startFrom={response.nextId}&maxItems={1 - 100}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
startFromanynoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results
maxItemsintnoThe number of items to return in the page. Valid values are 1 - 100. Defaults to 100 if not provided.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200Accepted - The zone changes will be returned in the response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - Zone not found
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zoneIdstringId of zone used for request
zoneChangesarray of zone changesarray of zone changes sorted by created time in descending order
startFromany(optional) The startFrom parameter that was sent in on the HTTP request. Will not be present if the startFrom parameter was not sent
nextIdany(optional) The identifier to be passed in as the startFrom parameter to retrieve the next page of results. If there are no results left, this field will not be present
maxItemsintThe maxItems parameter that was sent in on the HTTP request. This will be 100 if not sent
+ +

EXAMPLE RESPONSE

+ +
{
+  "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+  "zoneChanges": [
+      {
+        "status": "Synced",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.10.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:57Z",
+        "changeType": "Update",
+        "userId": "history-id",
+        "id": "6d4deccb-4632-475e-9ebc-3f6bace5fe68"
+      },
+      {
+        "status": "Synced",
+        "zone": {
+          "status": "Active",
+          "updated": "2016-12-30T15:37:57Z",
+          "name": "system-test-history.",
+          "adminGroupId": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "created": "2016-12-30T15:37:56Z",
+          "account": "67b4da23-6832-4600-8450-9fa0664caeeb",
+          "email": "i.changed.this.9.times@history-test.com",
+          "shared": true,
+          "acl": {
+            "rules": []
+          },
+          "id": "9f353bc7-cb8d-491c-b074-34afafc97c5f"
+        },
+        "created": "2016-12-30T15:37:57Z",
+        "changeType": "Update",
+        "userId": "history-id",
+        "id": "59c2db90-41aa-49ae-8c56-e13a2ada918d"
+      }
+  ],
+  "startFrom": "2910234",
+  "nextId": "1034932",
+  "maxItems": 2
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/list-zones.html b/api/list-zones.html new file mode 100644 index 000000000..4ec9c3681 --- /dev/null +++ b/api/list-zones.html @@ -0,0 +1,222 @@ +VinylDNS: List / Search Zones

List / Search Zone

+ +

Retrieves the list of zones a user has access to. The zone name is only sorted alphabetically.

+ +

HTTP REQUEST

+ +
+ + + + + + + +
GET /zones?nameFilter={yoursearchhere}&startFrom={response.nextId}&maxItems={1 - 100}&ignoreAccess={truefalse}
+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
nameFilterstringnoCharacters that are part of the zone name to search for. The wildcard character * is supported, for example www*. Omit the wildcard character when searching for an exact zone name.
startFromanynoIn order to advance through pages of results, the startFrom is set to the nextId that is returned on the previous response. It is up to the client to maintain previous pages if the client wishes to advance forward and backward. If not specified, will return the first page of results
maxItemsintnoThe number of items to return in the page. Valid values are 1 - 100. Defaults to 100 if not provided.
ignoreAccessbooleannoIf false, returns only zones the requesting user owns or has ACL access to. If true, returns zones in the system, regardless of ownership. Defaults to false if not provided.
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The zones and search info are returned in response body
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zonesArray of ZonesAn array of the zones found. The zones are sorted alphabetically by zone name.
startFromany(optional) The startFrom parameter that was sent in on the HTTP request. Will not be present if the startFrom parameter was not sent
nextIdany(optional) The identifier to be passed in as the startFrom parameter to retrieve the next page of results. If there are no results left, this field will not be present.
maxItemsintThe maxItems parameter that was sent in the HTTP request. This will be 100 if not sent.
ignoreAccessbooleanThe ignoreAccess parameter that was sent in the HTTP request. This will be false if not sent.
+ +

EXAMPLE RESPONSE

+ +
{
+  "zones": [
+    {
+      "status": "Active",
+      "account": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "name": "list-zones-test-searched-1.",
+      "created": "2016-12-16T15:21:47Z",
+      "adminGroupId": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "email": "test@test.com",
+      "shared": false,
+      "acl": {
+        "rules": []
+      },
+      "id": "31a3d8a9-bea0-458f-9c24-3d39d4b929d6",
+      "latestSync": "2016-12-16T15:27:26Z",
+      "accessLevel": "NoAccess"
+    },
+    {
+      "status": "Active",
+      "account": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "name": "list-zones-test-searched-2.",
+      "created": "2016-12-16T15:21:47Z",
+      "adminGroupId": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "email": "test@test.com",
+      "shared": false,
+      "acl": {
+        "rules": []
+      },
+      "id": "f1a376b2-2d8f-41f3-b8c8-9c9fba308f5d",
+      "latestSync": "2016-12-16T15:27:26Z",
+      "accessLevel": "Delete"
+    },
+    {
+      "status": "Active",
+      "account": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "name": "list-zones-test-searched-3.",
+      "created": "2016-12-16T15:21:47Z",
+      "adminGroupId": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "email": "test@test.com",
+      "shared": false,
+      "acl": {
+        "rules": []
+      },
+      "id": "568de57d-cb34-4f05-a9b5-35f9187490af",
+      "latestSync": "2016-12-16T15:27:26Z",
+      "accessLevel": "Read"
+    },
+    {
+      "status": "Active",
+      "account": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "name": "list-zones-test-unfiltered-1.",
+      "created": "2016-12-16T15:21:47Z",
+      "adminGroupId": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "email": "test@test.com",
+      "shared": false,
+      "acl": {
+        "rules": []
+      },
+      "id": "98dac90c-236e-4171-8729-c977ad38717e",
+      "latestSync": "2016-12-16T15:27:26Z",
+      "accessLevel": "NoAccess"
+    },
+    {
+      "status": "Active",
+      "account": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "name": "list-zones-test-unfiltered-2.",
+      "created": "2016-12-16T15:21:47Z",
+      "adminGroupId": "a0b5ea74-cc05-4932-a294-9bf935d52744",
+      "email": "test@test.com",
+      "shared": false,
+      "acl": {
+        "rules": []
+      },
+      "id": "e4942020-b85a-421f-a8e2-124d8ba79422",
+      "latestSync": "2016-12-16T15:27:26Z",
+      "accessLevel": "Read"
+    }
+  ],
+  "maxItems": 100,
+  "ignoreAccess": true
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/membership-model.html b/api/membership-model.html new file mode 100644 index 000000000..e58eb8ab6 --- /dev/null +++ b/api/membership-model.html @@ -0,0 +1,182 @@ +VinylDNS: Membership Model

Membership Model

+ +

Table of Contents

+ + + +

MEMBERSHIP BREAKDOWN

+ +

Every zone can be connected to by only one group in VinylDNS. That initial group will be the admin group for that zone, +which can be changed later on in a Zone Update. Every member of the admin group +will be an admin of that zone, and can preform zone syncs, zone updates, zone deletes, and record set changes regardless +of any Access Control Rules set on them. +

+While users in the admin group will have complete zone access, further users can be given limited membership through Zone +ACL Rules

+ +

GROUP ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
fieldtypedescription
namestringThis should be a single word name used for the groups. Use hyphens if needed, no spaces
emailstringThe email distribution list for the group
descriptionstringA short description of the group, if more info is needed other than the name. The group will not have this attribute if it was not included in the create request
idstringUnique UUID of the group
createddate-timeThe timestamp (UTC) when the group was created
statusstringActive or Deleted
membersArray of User id objectsSet of User ids in the group
adminsArray of User id objectsSet of User ids that are admins of the group. All admin user ids should also be in the members array
+ +

Being in the admin set of a group has no impact on zone privileges when the group is the zone’s admin group. Being a group admin allows adding users to +the group, deleting users from the group, toggling other users’ admin statuses (including your own), and deleting the group

+ +

GROUP EXAMPLE

+ +
{
+  "id": "dc4c7c79-5bbc-41bf-992e-8d6c4ec574c6",
+  "name": "some-group",
+  "email": "test@example.com",
+  "created": "2017-01-30T20:05:24Z",
+  "status": "Active",
+  "members": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    },
+    {
+      "id": "a6d35b1a-57d7-4a65-bec2-d7ed30a7c430"
+    }
+  ],
+  "admins": [
+    {
+      "id": "a6d35b1a-57d7-4a65-bec2-d7ed30a7c430"
+    }
+  ]
+}
+
+ +

USER ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
fieldtypedescription
userNamestringThis should be the AD username of the user
firstNamestringFirst name of the user
lastNamestringLast name of the user
emailstringEmail address of the user
createddate-timeThe timestamp (UTC) when the user was created
idstringUnique UUID of the user
isTestbooleanDefaults to false. Used for restricted access during VinylDNS testing, can be ignored by clients
+ +

To get your access and secret keys, log into the VinylDNS portal and then with the top right drop-down select Download Credentials

+ +

USER EXAMPLE

+ +
{
+  "userName": "jdoe201",
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john_doe@example.com",
+  "id": "1764183c-5e75-4ae6-8833-503cd5f4dcb3",
+  "isTest": false
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/recordset-model.html b/api/recordset-model.html new file mode 100644 index 000000000..959a791de --- /dev/null +++ b/api/recordset-model.html @@ -0,0 +1,421 @@ +VinylDNS: RecordSet Model

RecordSet Model

+ +

Table of Contents

+ + + +

RecordSet ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
fieldtypedescription
zoneIdstringthe id of the zone to which this recordset belongs
namestringThe name of the RecordSet
typestringType of DNS record, supported records are currently: A, AAAA, CNAME, DS, MX, NAPTR, NS, PTR, SOA, SRV, TXT, SSHFP, and SPF. Unsupported types will be given the type UNKNOWN
ttllongthe TTL in seconds for the recordset
statusstringActive - RecordSet is added is created and ready for use, Inactive - RecordSet effects are not applied, Pending - RecordSet is queued for creation, PendingUpdate - RecordSet is queued for update, PendingDelete - RecordSet is queued for delete
createddate-timeThe timestamp (UTC) when the recordset was created
updateddate-timeThe timestamp (UTC) when the recordset was last updated
recordsArray of RecordDataArray of record data, a single RecordSet can have multiple DNS records as long as they are all the same type
idstringthe id of the recordset. This is important as you will use it for other recordset operations
accountstringDEPRECATED The account that created the RecordSet
+ +

RecordSet EXAMPLE

+ +
{
+    "type": "A",
+    "zoneId": "8f8f649f-998e-4428-a029-b4ba5f5bd4ca",
+    "name": "foo",
+    "ttl": 38400,
+    "status": "Active",
+    "created": "2017-02-22T21:34:35Z",
+    "records": [
+        {
+            "address": "1.1.1.1"
+        },
+        {
+            "address": "2.2.2.2"
+        },
+        {
+            "address": "3.3.3.3"
+        }
+    ],
+    "id": "8306cce4-e16a-4579-9b19-4af46dc75853",
+    "account": "b34f8d18-646f-4843-a80a-7c0d58a22bf5"
+}
+
+ +

RECORD DATA INFORMATION

+

Current supported record types are: A, AAAA, CNAME, DS, MX, NAPTR, NS, PTR, SOA, SRV, TXT, SSHFP, and SPF. +Each individual record encodes its data in a record data object, in which each record type has different required attributes +

+SOA records and NS origin records (record with the same name as the zone) are currently read-only and cannot be created, updated or deleted. +Non-origin NS records can be created or updated for approved name servers only. Any non-origin NS record can be deleted.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
record typeattributetype
Aaddressstring

  
AAAAaddressstring

  
CNAMEcnamestring

  
DSkeytaginteger
DSalgorithminteger
DSdigesttypeinteger
DSdigeststring

  
MXpreferenceinteger
MXexchangestring

  
NAPTRorderinteger
NAPTRpreferenceinteger
NAPTRflagsstring
NAPTRservicestring
NAPTRregexpstring
NAPTRreplacementstring

  
NSnsdnamestring

  
PTRptrdnamestring

  
SOAmnamestring
SOArnamestring
SOAseriallong
SOArefreshlong
SOAretrylong
SOAexpirelong
SOAminimumlong

  
SPFtextstring

  
SRVpriorityinteger
SRVweightinteger
SRVportinteger
SRVtargetstring

  
SSHFPalgorithminteger
SSHFPtypeinteger
SSHFPfingerprintstring

  
TXTtextstring
+ +

RECORD DATA EXAMPLE

+ +

Each record is a map that must include all attributes for the data type, the records are stored in the records field of the RecordSet. +The records must be an array of at least one record map. All records in the records array must be of the type stored in the typ field of the RecordSet

+ +

Use the @ symbol to point to the zone origin

+ +

CNAME records cannot point to the zone origin, thus the RecordSet name cannot be @ nor the zone origin

+ +

Individual SSHFP record:

+ +
{
+    "type": "SSHFP",
+    "zoneId": "8f8f649f-998e-4428-a029-b4ba5f5bd4ca",
+    "name": "foo",
+    "ttl": 38400,
+    "status": "Active",
+    "created": "2017-02-22T21:34:35Z",
+    "records": [
+        {
+            "algorithm": 1,
+            "type": 3,
+            "fingerprint": "560c7d19d5da9a3a5c7c19992d1fbde15d8dad31"
+        }
+    ],
+    "id": "8306cce4-e16a-4579-9b19-4af46dc75853",
+    "account": "b34f8d18-646f-4843-a80a-7c0d58a22bf5"
+}
+
+ +

Multiple SSHFP records:

+ +
{
+    "type": "SSHFP",
+    "zoneId": "8f8f649f-998e-4428-a029-b4ba5f5bd4ca",
+    "name": "foo",
+    "ttl": 38400,
+    "status": "Active",
+    "created": "2017-02-22T21:34:35Z",
+    "records": [
+        {
+          "algorithm": 1,
+          "type": 2,
+          "fingerprint": "560c7d19d5da9a3a5c7c19992d1fbde15d8dad31"
+        },
+        {
+          "algorithm": 3,
+          "type": 1,
+          "fingerprint": "160c7d19d5da9a3a5c7c19992d1fbde15d8dad31"
+        },
+        {
+          "algorithm": 4,
+          "type": 1,
+          "fingerprint": "260c7d19d5da9a3a5c7c19992d1fbde15d8dad31"
+        }
+    ],
+    "id": "8306cce4-e16a-4579-9b19-4af46dc75853",
+    "account": "b34f8d18-646f-4843-a80a-7c0d58a22bf5"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/reject-batchchange.html b/api/reject-batchchange.html new file mode 100644 index 000000000..c586008ef --- /dev/null +++ b/api/reject-batchchange.html @@ -0,0 +1,211 @@ +VinylDNS: Reject Batch Change

Reject Batch Change

+ +

Manually rejects a batch change in pending review status given the batch change ID, resulting in immediate failure. Only +system administrators (i.e., support or super user) can manually review a batch change.

+ +

Note: If manual review is disabled in the VinylDNS instance, +users trying to access this endpoint will encounter a 404 Not Found response since it will not exist.

+ +

HTTP REQUEST

+ +
+

POST /zones/batchrecordchanges/{id}/reject

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
idstringyesUnique identifier assigned to each created batch change.
reviewCommentstringnoOptional rejection explanation.
+ +

EXAMPLE HTTP REQUEST

+
{
+    "reviewComment": "Comments are optional."
+}
+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK Batch change is rejected and is returned in response body.
400BadRequest Batch change is not in pending approval status.
403Forbidden User is not a system administrator (ie. support or super user).
404NotFound Batch change does not exist.
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
userIdstringThe unique identifier of the user that created the batch change.
userNamestringThe username of the user that created the batch change.
commentsstringConditional: comments about the batch change, if provided.
createdTimestampdate-timeThe timestamp (UTC) when the batch change was created.
changesArray of SingleChangeArray of single changes within a batch change. A SingleChange can either be a SingleAddChange or a SingleDeleteRRSetChange.
statusBatchChangeStatusStatus of the batch change.
idstringThe unique identifier for this batch change.
ownerGroupIdstringConditional: Record ownership assignment, if provided.
approvalStatusBatchChangeApprovalStatusWhether the batch change is currently awaiting manual review. Will be Rejected status when rejecting.
reviewerIdstringUnique identifier for the reviewer of the batch change.
reviewerUserNamestringUser name for the reviewer of the batch change.
reviewCommentstringConditional: Comment from the reviewer of the batch change, if provided.
reviewTimestampdate-timeThe timestamp (UTC) of when the batch change was manually reviewed.
+ +

EXAMPLE RESPONSE

+ +
{
+    "userId": "vinyl", 
+    "userName": "vinyl201", 
+    "comments": "this is optional", 
+    "createdTimestamp": "2019-07-25T20:22:53Z",
+    "changes": [
+        {
+            "changeType": "Add",
+            "inputName": "reject.parent.com.",
+            "type": "A",
+            "ttl": 7200,
+            "record": {
+                "address": "1.2.3.4"
+            },
+            "status": "Rejected",
+            "recordName": "",
+            "zoneName": "",
+            "zoneId": "",
+            "validationErrors": [
+                {
+                    "errorType": "ZoneDiscoveryError",
+                    "message": "Zone Discovery Failed: zone for \"reject.parent.com.\" does not exist in VinylDNS. If zone exists, then it must be connected to in VinylDNS."
+                }
+            ],
+            "id": "db811a02-5b0f-44ad-8ad9-8ecac7ba6bb4"
+        }
+    ],
+    "status": "Failed",
+    "id": "50e1b48b-80fa-41e0-96ef-72438abc31ec",
+    "ownerGroupId": "159a41c5-e67e-4951-b539-05f5ac788139",
+    "reviewerId": "90c11ffc-5a71-4794-97c6-74d19c81af7d ",
+    "reviewComment": "We can't make *this* change - are you out of your mind?!",
+    "reviewTimestamp": "2019-07-25T20:33:41Z",
+    "approvalStatus": "Rejected"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/sync-zone.html b/api/sync-zone.html new file mode 100644 index 000000000..cc22222f0 --- /dev/null +++ b/api/sync-zone.html @@ -0,0 +1,148 @@ +VinylDNS: Sync Zone

Sync Zone

+ +

Used to sync VinylDNS zone info with existing zone info. When a sync is performed, a zone transfer is initiated with the backend DNS server. +The backend data is compared to the existing data in VinylDNS. If there are any differences, the backend DNS Server is considered +the source of truth and will overwrite the data in VinylDNS. All changes will be recorded in VinylDNS so they can be seen in the +zone history.

+ +

While the zone is syncing, the zone will be unavailable for updates (read-only).

+ +

We have done some testing on how long syncs take. These will vary with usage:

+ +
    +
  • 1000 records ~ 1 second
    • +
  • 10,000 records ~ 10 seconds
    • +
  • 100,000 records ~ 6 minutes
    • +
+ +

Please keep these numbers in mind when you perform syncs.

+ +

HTTP REQUEST

+ +
+

POST /zones/{zoneId}/sync

+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - Successful lookup, the zone is returned in the response body
400Bad Request - invalid sync state, a sync has been performed recently, or zone is inactive
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - the user does not have the access required to perform the action
404Not Found - Zone not found
409Conflict - Zone has a pending update
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
statusstringSync status
zonemapRefer to zone model
createdstringThe timestamp (UTC) the sync was initiated
changeTypestringType of change requested (Create, Update, Sync, Delete); in this case Sync
userIdstringThe user ID that initiated the change
idstringThe ID of the change. This is not the id of the zone
+ +

EXAMPLE RESPONSE

+ +
{
+  "status": "Pending",
+  "zone": {
+    "status": "Syncing",
+    "updated": "2016-12-28T19:22:02Z",
+    "name": "sync-test.",
+    "adminGroupId": "cf00d1e4-46f1-493a-a3be-0ae79dd306a5",
+    "created": "2016-12-28T19:22:01Z",
+    "account": "cf00d1e4-46f1-493a-a3be-0ae79dd306a5",
+    "email": "test@test.com",
+    "shared": false,
+    "acl": {
+      "rules": []
+    },
+    "id": "621a13df-a2e3-4394-84c0-3eb3a664dff4"
+  },
+  "created": "2016-12-28T19:22:02Z",
+  "changeType": "Sync",
+  "userId": "ok",
+  "id": "03f1ee91-9053-4346-8b53-e0f6042600f2"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/update-group.html b/api/update-group.html new file mode 100644 index 000000000..8487cc054 --- /dev/null +++ b/api/update-group.html @@ -0,0 +1,229 @@ +VinylDNS: Update Group

Update Group

+ +

Updates a Group in VinylDNS

+ +

HTTP REQUEST

+ +
+

PUT /groups/{groupId}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
idstringyesThe ID of the group
namestringyesThe name of the group. Should be one word, use hyphens if needed but no spaces
emailstringyesThe email distribution list for the group
descriptionstringnoA short description of the group, if more info is needed other than the name
createddate-timeyesThe timestamp (UTC) when the group was created
statusstringyesActive or Deleted, should not be changed in an update, a delete request will handle deleting a group
membersArray of User ID objectsyesSet of User IDs in the group
adminsArray of User ID objectsyesSet of User IDs that are admins of the group. All admin user ids should also be in the members array
+ +

EXAMPLE HTTP REQUEST

+ +
{
+  "id": "6f8afcda-7529-4cad-9f2d-76903f4b1aca",
+  "name": "some-group",
+  "email": "test@example.com",
+  "created": "Thu Mar 02 2017 10:29:21",
+  "status": "Active",
+  "members": [
+    {
+      "id": "4764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    },
+    {
+      "id": "k8630ebc-0af2-4c9a-a0a0-d18c590ed03e"
+    }
+  ],
+  "admins": [
+    {
+      "id": "4764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    }
+  ]
+}
+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200OK - The group has been updated and the group info is returned in the response body
400Bad Request - The group was invalid or a user id was not found
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - The group was not found
409Conflict - The group already exists
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
idstringUnique UUID of the group
namemapThe name of the group
emailstringThe email distribution list of the group
descriptionstringThe group description, the group will not have this attribute if it was not included in the update request and already did not exist
createdstringThe timestamp (UTC) the group was created
statusstringActive or Deleted, in this case Active
membersArray of User Id objectsIds of members of the group including admins
adminsArray of User Id objectsIds of admins of the group
+ +

EXAMPLE RESPONSE

+ +
{
+  "id": "6f8afcda-7529-4cad-9f2d-76903f4b1aca",
+  "name": "some-group",
+  "email": "test@example.com",
+  "created": "2017-03-02T15:29:21Z",
+  "status": "Active",
+  "members": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    },
+    {
+      "id": "c8630ebc-0af2-4c9a-a0a0-d18c590ed03e"
+    }
+  ],
+  "admins": [
+    {
+      "id": "2764183c-5e75-4ae6-8833-503cd5f4dcb0"
+    }
+  ]
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/update-recordset.html b/api/update-recordset.html new file mode 100644 index 000000000..ed93dee1a --- /dev/null +++ b/api/update-recordset.html @@ -0,0 +1,264 @@ +VinylDNS: Update RecordSet

Update RecordSet

+ +

Updates a RecordSet. This performs a delete of the old record, and inserts the new record. +

+ +

HTTP REQUEST

+ +
+

PUT /zones/{zoneId}/recordsets/{recordSetId}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametyperequired?description
zoneIdstringyesid of the zone where the recordset belongs, this value must match the zoneId of the existing recordSet
idstringyesthe id of the recordset being updated
namestringyesthe name of the recordset being updated
typestringyesthe type of recordset
ttlintegeryesthe TTL in seconds
recordsarray of record datayesrecord data for recordset, see RecordSet Model
ownerGroupIdstringsometimes*Record ownership assignment, applicable if the recordset is in a shared zone
+ +

*Note: If a recordset has an ownerGroupId you must include that value in the update request, otherwise the update will remove the ownerGroupId value

+ +

EXAMPLE HTTP REQUEST

+
{
+  "id": "dd9c1120-0594-4e61-982e-8ddcbc8b2d21",
+  "name": "already-exists",
+  "type": "A",
+  "ttl": 38400,
+  "records": [
+    {
+      "address": "6.5.4.3"
+    }
+  ],
+  "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+  "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe"
+}
+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
202Accepted - the update is valid and has been accepted for processing; the record set change resource is returned in the response body
400Bad Request - the zone being updated is not active; typically because the connection information does not exist for the zone
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - The user does not have the access required to perform the action
404Not Found - Zone or RecordSet not found
409Conflict - There is an existing pending change against this record set
422Unprocessable Entity
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zonemapContains information about the zone when the change was created
recordSetmapContains the recordset model
updatesmapNew data to overwrite current record set
userIdstringThe user id that initiated the change
changeTypestringType of change requested (Create, Update, Delete); in this case Update
createdstringThe timestamp (UTC) the change was initiated
idstringThe ID of the change. This is not the ID of the recordset
statusRecordSetChangeStatusThe status of the change (Pending, Complete, or Failed)
singleBatchChangeIdsarray of SingleBatchChange ID objectsIf the recordset change was part of a batch change, the IDs of the single changes that comprise the recordset change
+ +

EXAMPLE RESPONSE

+ +
{
+  "zone": {
+    "name": "vinyl.",
+    "email": "test@test.com",
+    "status": "Active",
+    "created": "2017-02-23T14:52:44Z",
+    "updated": "2017-02-23T15:12:33Z",
+    "id": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "shared": false,
+    "acl": {
+      "rules": [
+
+      ]
+    },
+    "adminGroupId": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "latestSync": "2017-02-23T15:12:33Z"
+  },
+  "recordSet": {
+    "type": "A",
+    "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "name": "already-exists",
+    "ttl": 38400,
+    "status": "PendingUpdate",
+    "created": "2017-02-23T15:12:41Z",
+    "updated": "2017-02-23T15:12:41Z",
+    "records": [
+      {
+        "address": "6.6.6.1"
+      }
+    ],
+    "id": "dd9c1120-0594-4e61-982e-8ddcbc8b2d21",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae"
+  },
+  "userId": "0215d410-9b7e-4636-89fd-b6b948a06347",
+  "changeType": "Update",
+  "status": "Pending",
+  "created": "2017-02-23T15:12:41Z",
+  "updates": {
+    "type": "A",
+    "zoneId": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "name": "already-exists",
+    "ttl": 38400,
+    "status": "Active",
+    "created": "2017-02-23T15:12:33Z",
+    "records": [
+      {
+        "address": "6.6.6.6"
+      }
+    ],
+    "id": "dd9c1120-0594-4e61-982e-8ddcbc8b2d21",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "ownerGroupId": "f42385e4-5675-38c0-b42f-64105e743bfe"
+  },
+  "id": "df69bc45-2942-4fb7-813c-4dd21cfad7fa",
+  "singleBatchChangeIds": []
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/update-zone.html b/api/update-zone.html new file mode 100644 index 000000000..98ac5d8a2 --- /dev/null +++ b/api/update-zone.html @@ -0,0 +1,166 @@ +VinylDNS: Update Zone

Update Zone

+ +

Updates an existing zone that has already been connected to. Used to update the ACL rules or zone level meta data like the zone connection or email.

+ +

HTTP REQUEST

+ +
+

PUT /zones/{zoneId}

+
+ +

HTTP REQUEST PARAMS

+ + + + + + + +
zone fields, refer to zone model
+ +

EXAMPLE HTTP REQUEST

+ +
{
+  "name": "vinyl.",
+  "email": "update@update.com",
+  "status": "Active",
+  "created": "2017-02-23T14:52:44Z",
+  "updated": "2017-02-23T19:05:33Z",
+  "id": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+  "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+  "shared": false,
+  "acl": {
+    "rules": []
+  },
+  "adminGroupId": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+  "latestSync": "2017-02-23T19:05:33Z",
+  "adminGroupName": "test",
+  "hiddenKey": "",
+  "hiddenTransferKey": ""
+}
+
+ +

HTTP RESPONSE TYPES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codedescription
200Accepted - The zone change is returned in the response body
400Bad Request - connection failed
401Unauthorized - The authentication information provided is invalid. Typically the request was not signed properly, or the access key and secret used to sign the request are incorrect
403Forbidden - the user does not have the access required to perform the action
404Not Found - Zone not found
409Conflict - Zone has a pending update
+ +

HTTP RESPONSE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
nametypedescription
zonemapZone sent with update request, refer to zone model
userIdstringThe user id that initiated the change
changeTypestringType of change requested (Create, Update, Sync, Delete); in this case Update
createdstringThe timestamp (UTC) the change was initiated
idstringThe ID of the change. This is not the ID of the zone
statusstringThe status of the zone change
+ +

EXAMPLE RESPONSE

+ +
{
+  "zone": {
+    "name": "vinyl.",
+    "email": "update@update.com",
+    "status": "Active",
+    "created": "2017-02-23T14:52:44Z",
+    "updated": "2017-02-23T19:23:26Z",
+    "id": "2467dc05-68eb-4498-a9d5-78d24bb0893c",
+    "account": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "shared": false,
+    "acl": {
+      "rules": []
+    },
+    "adminGroupId": "9b22b686-54bc-47fb-a8f8-cdc48e6d04ae",
+    "latestSync": "2017-02-23T19:05:33Z"
+  },
+  "userId": "0215d410-9b7e-4636-89fd-b6b948a06347",
+  "changeType": "Update",
+  "status": "Pending",
+  "created": "2017-02-23T19:23:26Z",
+  "id": "d1fcd28d-61fe-4c24-ac0b-4377d66d50db"
+}
+
+
Improve this page
\ No newline at end of file diff --git a/api/zone-model.html b/api/zone-model.html new file mode 100644 index 000000000..9eb60d16d --- /dev/null +++ b/api/zone-model.html @@ -0,0 +1,414 @@ +VinylDNS: Zone Model

Zone Model

+ +

Table of Contents

+ + + +

ZONE ATTRIBUTES

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
fieldtypedescription
statusstringActive - the zone is connected and ready for use; Syncing - the zone is currently syncing with the DNS backend and is not available until syncing is complete.
updateddate-timeThe last time the zone was changed. Note: this does not include changes to record sets, only the zone entity itself
namestringThe name of the zone
adminGroupIdstringThe id of the administrators group for the zone
createddate-timeThe time when the zone was first created
accountstringDEPRECATED The account that created the zone
emailstringThe distribution email for the zone
backendIdstringOptional. Recommended over connection and transferConnection. The configuration ID of the DNS backend server for the zone. If not provided, default keys will be used unless connection and transfer connection are provided.
connectionZoneConnectionOptional. The connection used to issue DDNS updates to the backend zone. If not provided, default keys will be used unless backendId is provided. See the Zone Connection Attributes for more information
transferConnectionZoneConnectionOptional. The connection that is used to sync the zone with the DNS backend. This can be different than the update connection. If not provided, default keys will be used unless backendId is provided.
sharedbooleanAn indicator that the zone is shared with anyone. At this time only VinylDNS administrators can set this to true.
aclZoneACLThe access control rules governing the zone. See the Zone ACL Rule Attributes for more information
idstringThe unique identifier for this zone
latestSyncdate-timeThe last date and time the zone was synced
isTestbooleanDefaults to false. Used for restricted access during VinylDNS testing, can be ignored by clients
accessLevelstringAccess level of the user requesting the zone. Current levels are Delete (full access), Read and NoAccess.
+ +

ZONE EXAMPLE

+ +
{
+  "status": "Active",
+  "updated": "2016-12-16T15:27:28Z",
+  "name": "ok.",
+  "adminGroupId": "92b298e8-97db-4f1b-881b-fd08ca0dd311",
+  "created": "2016-12-16T15:27:26Z",
+  "account": "92b298e8-97db-4f1b-881b-fd08ca0dd311",
+  "email": "test@test.com",
+  "connection": {
+    "primaryServer": "127.0.0.1:5301",
+    "keyName": "vinyl.",
+    "name": "ok.",
+    "key": "OBF:1:W1FXgpOjjrQAABAARrZmyLjFSOuFYTAw81mhvNEmNAc4RnYzPjJQMEjVQWWLRohu7gRAVw=="
+  },
+  "transferConnection": {
+    "primaryServer": "127.0.0.1:5301",
+    "keyName": "vinyl.",
+    "name": "ok.",
+    "key": "OBF:1:W1FXgpOjjrQAABAARrZmyLjFSOuFYTAw81mhvNEmNAc4RnYzPjJQMEjVQWWLRohu7gRAVw=="
+  },
+  "shared": false,
+  "acl": {
+    "rules": [
+      {
+        "accessLevel": "Write",
+        "userId": "<uuid>",
+        "description": "some_test_rule",
+        "recordTypes": []
+      },
+      {
+        "recordMask": ".*",
+        "accessLevel": "Write",
+        "userId": "<uuid>",
+        "description": "some_test_rule",
+        "recordTypes": []
+      },
+      {
+        "recordMask": "test.*",
+        "accessLevel": "Read",
+        "groupId": "<uuid>",
+        "description": "some_test_rule",
+        "recordTypes": []
+      }
+    ]
+  },
+  "id": "9cbdd3ac-9752-4d56-9ca0-6a1a14fc5562",
+  "latestSync": "2016-12-16T15:27:26Z",
+  "backendId":"func-test-backend",
+  "accessLevel": "Delete"
+}
+
+ +

ZONE ACL RULE ATTRIBUTES

+

ACL Rules are used to govern user and group access to record operations on a zone. ACL Rules can be associated with a specific user, or all users in a specified group. If neither a user or a group is attached to an ACL rule, then the rule applies to all users in the system. +

+Use the Zone Update endpoint to update the acl attribute of the zone

+ +
+

Important! If a user is mentioned on an ACL Rule directly, or is a member of a group that is mentioned on an ACL Rule, that user will be able to see the zone.

+
+ +
+

Rules made without selecting a group or user will apply to all users in VinylDNS.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
fieldtypedescription
recordMaskstring(optional) A regular expression that is used to match against record names. If left empty, then all records will be matched for the rule. All records matching the match will be governed by this rule.
recordTypesArray[String]An array of all record types that this rule applies to. If left empty, then all record types will be governed by this rule.
accessLevelstringNoAccess - cannot see the data for the record; Read - can read only the record; Write - the user can create and edit records, but cannot delete them; Delete - the user can read, create, update, and delete records
userIdstring(optional) The unique identifier for the user the rule applies to. Note: this is not the name of the user, but their uuid in VinylDNS
groupIdstring(optional) The unique identifier for the group the rule applies to. Note: you cannot set both the userId and groupId, only one
descriptionstring(optional) A user entered description for the rule
+ +

The priority of ACL Rules in descending precedence:

+
    +
  1. Individual rules placed on a user
    2. +
  2. Rules placed on groups that a user is in
    3. +
  3. Rules placed on all users in VinylDNS
    4. +
+ +
+

Note: Being in the admin group of a zone will grant users full access regardless of ACL Rules

+
+ +

For conflicting rules, the rule that is more specific will take precedence. For example, if the account jdoe201 was given Read access to all records in a zone +through the rule:

+ +
{
+  "userId": "<uuid>",
+  "accessLevel": "Read",
+}
+
+ +

and then Write access to only A records through the rule:

+ +
{
+  "userId": "<uuid>",
+  "accessLevel": "Write",
+  "recordTypes": ["A"]
+}
+
+ +

and then Delete access to only A records that matched the expression *dev* through the rule:

+ +
{
+  "userId": "<uuid>",
+  "accessLevel": "Delete",
+  "recordTypes": ["A"],
+  "recordMask": "*dev*"
+}
+
+ +

then the rule with the recordMask will take precedence and give Delete access to matched A RecordSets, the rule with recordTypes will +take precedence and give Write access to all other A records, and the more broad rule will give Read access to all other record types in the zone

+ +

ZONE ACL RULE EXAMPLES

+

Grant read/write/delete access to www.* records of type A, AAAA, CNAME to one user +Under this rule, the user specified will be able to view, create, edit, and delete records in the zone that match the expression www.* and are of type A, AAAA, or CNAME.

+ +
{
+  "recordMask": "www.*",
+  "accessLevel": "Delete",
+  "userId": "<uuid>",
+  "recordTypes": ["A", "AAAA", "CNAME"]
+}
+
+ +

Grant read only access to all VinylDNS users to A, AAAA, CNAME records

+ +
{
+  "accessLevel": "Read",
+  "recordTypes": ["A", "AAAA", "CNAME"]
+}
+
+ +

Grant read/write/delete access to records of type A, AAAA, CNAME to one group*

+ +
{
+  "accessLevel": "Delete",
+  "groupId": "<uuid>",
+  "recordTypes": ["A", "AAAA", "CNAME"]
+}
+
+ +

PTR ACL RULES WITH CIDR MASKS

+

ACL rules can be applied to specific record types and can include record masks to further narrow down which records they +apply to. These record masks apply to record names, but because PTR record names are part their reverse zone ip, the use of regular +expressions for record masks are not supported. +

+Instead PTR record masks must be CIDR rules, which will denote a range of IP addresses that the rule will apply to. +While more information and useful CIDR rule utility tools can be found online, CIDR rules describe how many bits of an ip address’ binary representation +must be the same for a match.

+ +

PTR ACL RULES WITH CIDR MASKS EXAMPLE

+

The ACL Rule

+ +
{
+    "recordTypes": ["PTR"],
+    "accessLevel": "Read"
+}
+
+ +

Will give Read permissions to PTR Record Sets to all users in VinylDNS +

+The IPv4 ACL Rule

+ +
{
+    "recordTypes": ["PTR"],
+    "accessLevel": "Read",
+    "recordMask": "100.100.100.100/16"
+}
+
+ +

Will give Read permissions to PTR Record Sets 100.100.000.000 to 100.100.255.255, as 16 bits is half of an IPv4 address +

+The IPv6 ACL Rule

+ +
{
+    "recordTypes": ["PTR"],
+    "accessLevel": "Read",
+    "recordMask": "1000:1000:1000:1000:1000:1000:1000:1000/64"
+}
+
+ +

Will give Read permissions to PTR Record Sets 1000:1000:1000:1000:0000:0000:0000:0000 to 1000:1000:1000:1000:FFFF:FFFF:FFFF:FFFF, as 64 bits is half of an IPv6 address.

+ +

ZONE CONNECTION ATTRIBUTES

+

In order for VinylDNS to make updates in DNS, it needs key information for every zone. There are 3 ways to specify that key information; ask your VinylDNS admin which is appropriate for your zone based on the configuration of the service:

+ +
    +
  1. Leave connection, transfer connection, and backend ID blank: In this case, the default VinylDNS keys will be used
    2. +
  2. Specify a backend ID on the zone: if multiple backends are configured for your instance of VinylDNS, you can specify a backend ID on the zone and the keys associated with that backend will be used.
    3. +
  3. Specify zone connection and transfer connection on the zone itself: see below for details
    4. +
+ +

Note that if both a backend ID and specific connection keys are included on a zone, the specific connection keys will be used.

+ +

Zone Connection specifies the connection information to the backend DNS server.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
fieldtypedescription
primaryServerstringThe IP address or host that is connected to. This can take a port as well 127.0.0.1:5300. If no port is specified, 53 will be assumed.
keyNamestringThe name of the DNS key that has access to the DNS server and zone. Note: For the transfer connection, the key must be given allow-transfer access to the zone. For the primary connection, the key must be given allow-update access to the zone.
namestringA user identifier for the connection.
keystringThe TSIG secret key used to sign requests when communicating with the primary server. Note: After creating the zone, the key value itself is hashed and obfuscated, so it will be unusable from a client perspective.
+ +

ZONE CONNECTION EXAMPLE

+ +
{
+  "primaryServer": "127.0.0.1:5301",
+  "keyName": "vinyl.",
+  "name": "ok.",
+  "key": "OBF:1:W1FXgpOjjrQAABAARrZmyLjFSOuFYTAw81mhvNEmNAc4RnYzPjJQMEjVQWWLRohu7gRAVw=="
+}
+
+ +

SHARED ZONES

+ +

Shared zones allow for a more open management of records in VinylDNS. Zone administrators can assign ownership of +records to groups. Any user in VinylDNS can claim existing unowned records in shared zones, as well as create records in +those zones. Once a record is owned, only users in the record owner group, the zone administrators and those with +relevant ACL rules can modify or delete the record. The batch change API endpoint +and DNS change area of the portal are where users can create new records in shared zones, +modify records they own, or claim unowned records. If a zone’s shared state changes to false the record ownership access +is no longer applicable.

+
Improve this page
\ No newline at end of file