Skip to content

fix(api-catalog): resync spec drift and support TLSA DNS records #244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jpage-godaddy wants to merge 2 commits into from
Open

fix(api-catalog): resync spec drift and support TLSA DNS records #244

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fda0f2c
fix(api-catalog): resync spec drift and support TLSA DNS records
jpage-godaddy Sep 3, 2026
d7b9e62
fix(dns): use the same "(no data)" placeholder for missing data in de…
jpage-godaddy Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 99 additions & 7 deletions rust/domains-client/openapi/domains.oas3.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -729,10 +729,30 @@
"DNSRecord": {
"$id": "https://godaddy.com/schemas/domains/domain-lifecycle/dns-record.v3",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "A single DNS resource record in the zone for a domain managed by GoDaddy DNS. Supports standard IANA record types plus the GoDaddy ALIAS extension. SOA records are read-only and managed by GoDaddy's authoritative DNS infrastructure. The record is uniquely identified by the combination of name, type, and data. HTTPS and SVCB records (RFC 9460) use the priority field for SvcPriority and the optional parameters field for SvcParams.\n",
"description": "A single DNS resource record in the zone for a domain managed by GoDaddy DNS. Supports standard IANA record types plus the GoDaddy ALIAS extension. SOA records are read-only and managed by GoDaddy's authoritative DNS infrastructure. The record is uniquely identified by its type-specific key fields: name, type, and data for most record types; name, type, usage, selector, matchingType, and certificateData for TLSA records. HTTPS and SVCB records (RFC 9460) use the priority field for SvcPriority and the optional parameters field for SvcParams. TLSA records (RFC 6698) require usage, selector, matchingType, and certificateData instead of data; the DNS name is composed as _port._proto.name from the port, protocol, and name fields. All other record types require data.\n",
"else": {
"required": [
"data"
]
},
"if": {
"properties": {
"type": {
"const": "TLSA"
}
},
"required": [
"type"
]
},
"properties": {
"certificateData": {
"description": "Hex-encoded certificate association data (RFC 6698; TLSA only). Content depends on selector and matchingType: the full DER-encoded certificate or SubjectPublicKeyInfo (matchingType 0), or its SHA-256 (matchingType 1) or SHA-512 (matchingType 2) digest. Must be an even number of hex digits (whole bytes). Supplying this field for any other record type is ignored.\n",
"example": "d2abde240d7cd3ee6b4b28c54df034b97983a1d16e8a410e4561cb106618e971",
"type": "string"
},
"data": {
"description": "The record data, formatted per the record type. For MX: the mail exchange hostname (e.g. \"mail.example.com.\"). Supply priority as the sibling priority field. For SRV: the target hostname; supply priority, weight, port, service, and protocol as sibling fields. For TXT: the text value (quotes are handled by the DNS layer). For A/AAAA: the IP address. For CNAME/ALIAS: the target hostname with trailing dot. For HTTPS/SVCB: the target hostname (\".\" for the zone apex); supply priority as SvcPriority and optional SvcParams in the sibling parameters field.\n",
"description": "The record data, formatted per the record type. For MX: the mail exchange hostname (e.g. \"mail.example.com.\"). Supply priority as the sibling priority field. For SRV: the target hostname; supply priority, weight, port, service, and protocol as sibling fields. For TXT: the text value (quotes are handled by the DNS layer). For A/AAAA: the IP address. For CNAME/ALIAS: the target hostname with trailing dot. For HTTPS/SVCB: the target hostname (\".\" for the zone apex); supply priority as SvcPriority and optional SvcParams in the sibling parameters field. Not used for TLSA records; supply usage, selector, matchingType, and certificateData instead.\n",
"example": "192.0.2.1",
"type": "string"
},
Expand All @@ -743,6 +763,9 @@
"minimum": 0,
"type": "integer"
},
"matchingType": {
"$ref": "#/components/schemas/TLSAMatchingType"
},
"name": {
"description": "The DNS record name (label), relative to the zone apex. Use @ to represent the zone apex itself. Wildcards (*) are supported for A, AAAA, and CNAME records.\n",
"example": "@",
Expand Down Expand Up @@ -776,8 +799,11 @@
"readOnly": true,
"type": "string"
},
"selector": {
"$ref": "#/components/schemas/TLSASelector"
},
"service": {
"description": "Service name for SRV and TLSA records, prefixed with an underscore (e.g. `_http`, `_smtp`). Combined with the protocol to form the record name as `_service._proto.name`.\n",
"description": "Service name for SRV records, prefixed with an underscore (e.g. `_http`, `_smtp`). Combined with the protocol to form the record name as `_service._proto.name`.\n",
"example": "_http",
"type": "string"
},
Expand All @@ -799,11 +825,14 @@
"$ref": "#/components/schemas/DNSRecordType"
},
{
"description": "The DNS resource record type. Together with name and data, uniquely identifies this record in the zone. Determines the expected data format and which optional fields (priority, service, port, etc.) apply. SOA and NS records are read-only.\n",
"description": "The DNS resource record type. Together with name and the type-specific record data fields, uniquely identifies this record in the zone. Determines the expected data format and which optional fields (priority, service, port, etc.) apply. SOA and NS records are read-only.\n",
"example": "A"
}
]
},
"usage": {
"$ref": "#/components/schemas/TLSAUsage"
},
"weight": {
"description": "Relative weight for load distribution among SRV records with equal priority. Higher values increase the probability of selection. Use 0 when only one target exists at a given priority.\n",
"example": 10,
Expand All @@ -815,16 +844,23 @@
"required": [
"name",
"type",
"data",
"ttl"
],
"then": {
"required": [
"usage",
"selector",
"matchingType",
"certificateData"
]
},
"title": "DNS Record",
"type": "object"
},
"DNSRecordType": {
"$id": "https://godaddy.com/schemas/domains/domain-lifecycle/dns-record-type.v3",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The type of a DNS resource record. Values correspond to IANA-assigned DNS record type mnemonics. A — IPv4 address record. AAAA — IPv6 address record. CAA — certification authority authorization record. CNAME — canonical name alias record. HTTPS — HTTPS service binding record (RFC 9460); data is the target hostname, priority is the SvcPriority (0 = AliasMode), and optional SvcParams are supplied in the sibling parameters field. MX — mail exchange record; data is the mail exchange hostname, priority is the sibling priority field. NS — nameserver delegation record; read-only. SOA — start of authority record; managed by the registry; read-only. SRV — service locator record. SVCB — service binding record (RFC 9460); same structure as HTTPS but for non-HTTP services. TXT — free-form text; used for SPF, DKIM, DMARC, and domain verification.\n",
"description": "The type of a DNS resource record. Values correspond to IANA-assigned DNS record type mnemonics. A — IPv4 address record. AAAA — IPv6 address record. CAA — certification authority authorization record. CNAME — canonical name alias record. HTTPS — HTTPS service binding record (RFC 9460); data is the target hostname, priority is the SvcPriority (0 = AliasMode), and optional SvcParams are supplied in the sibling parameters field. MX — mail exchange record; data is the mail exchange hostname, priority is the sibling priority field. NS — nameserver delegation record; read-only. SOA — start of authority record; managed by the registry; read-only. SRV — service locator record. SVCB — service binding record (RFC 9460); same structure as HTTPS but for non-HTTP services. TLSA — TLS certificate association record (RFC 6698); used for DANE. TXT — free-form text; used for SPF, DKIM, DMARC, and domain verification.\n",
"title": "DNS Record Type",
"type": "string"
},
Expand Down Expand Up @@ -1703,6 +1739,48 @@
"title": "Suggestion Source",
"type": "string"
},
"TLSAMatchingType": {
"$id": "https://godaddy.com/schemas/domains/domain-lifecycle/tlsa-matching-type.v3",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "TLSA matching type (RFC 6698 §2.1.3). Specifies how the selected certificate material is compared to the association data. Values outside the defined set (3–255) are not currently supported and will be rejected. 0 — Exact match: association data is compared byte-for-byte to the selected content. 1 — SHA-256: association data is the SHA-256 digest of the selected content. 2 — SHA-512: association data is the SHA-512 digest of the selected content.\n",
"examples": [
0,
1,
2
],
"maximum": 255,
"minimum": 0,
"title": "TLSA Matching Type",
"type": "integer"
},
"TLSASelector": {
"$id": "https://godaddy.com/schemas/domains/domain-lifecycle/tlsa-selector.v3",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "TLSA selector (RFC 6698 §2.1.2). Specifies which part of the TLS certificate is matched against the association data. Values outside the defined set (2–255) are not currently supported and will be rejected. 0 — Full certificate: the entire DER-encoded certificate. 1 — SubjectPublicKeyInfo: the DER-encoded SubjectPublicKeyInfo of the certificate.\n",
"examples": [
0,
1
],
"maximum": 255,
"minimum": 0,
"title": "TLSA Selector",
"type": "integer"
},
"TLSAUsage": {
"$id": "https://godaddy.com/schemas/domains/domain-lifecycle/tlsa-usage.v3",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "TLSA certificate usage (RFC 6698 §2.1.1). Constrains how the certificate association data is interpreted during DANE authentication. Values outside the defined set (4–255) are not currently supported and will be rejected. 0 — PKIX-TA (CA constraint): association must match a trust anchor in the PKIX validation path. 1 — PKIX-EE (service certificate constraint): association must match the end-entity certificate, which must also pass PKIX validation. 2 — DANE-TA (trust anchor assertion): association is a trust anchor for DANE validation; PKIX path building is not required. 3 — DANE-EE (domain-issued certificate): association must match the end-entity certificate; PKIX validation is not required.\n",
"examples": [
0,
1,
2,
3
],
"maximum": 255,
"minimum": 0,
"title": "TLSA Usage",
"type": "integer"
},
"Term": {
"$id": "https://godaddy.com/schemas/domains/domain-lifecycle/term.v3",
"$schema": "https://json-schema.org/draft/2020-12/schema",
Expand Down Expand Up @@ -2067,7 +2145,7 @@
},
"description": "The GoDaddy Domain Lifecycle Management API provides comprehensive capabilities\nfor discovering, registering, managing, renewing, transferring, and reselling\ndomain names. This is major version 3, designed for agent-first interactions\nwhile remaining fully usable by direct API clients and resellers.\n\n## Namespace\n\nAll paths are under `/v3/domains/`. The namespace is `domains` (the business capability);\nthe core entity collection is `/domain-names`.\n\n## Key Conventions\n\n**Quote/execute for commercial operations.** Every commercial mutation (register,\nrenew, transfer) requires a `quoteToken` minted by the corresponding quote\ncollection endpoint. Execution without a prior quote is structurally impossible.\nThe token locks the price, resolved settings, and required legal agreements for a\n10-minute TTL. Quote calls are free, read-only, and safe to call speculatively.\n\n**Async commercial operations.** `POST /registrations`, `POST /renewals`, and\n`POST /transfers` each return `202 Accepted` with the concrete entity body\n(`Registration`, `Renewal`, or `Transfer`) and a `Location` header. Poll\n`links[rel=self]` on the returned entity until status is `COMPLETED` or `FAILED`.\nEach concrete resource is also reachable via `GET /operations/{operationId}`;\nthe `operationId` is included in the entity for clients that prefer the abstract\nview. Non-commercial mutations return a `DomainOperation` body.\n\n**Entity-oriented resource model.** Domains are the core entity of this API\n(exposed as `/domain-names` in the path to distinguish the resource collection\nfrom the `domains` namespace prefix). Register, renew, and transfer are\ncommercial actions executed by `POST` to their corresponding top-level\nresource collections (`/registrations`, `/renewals`, `/transfers`); each\naccepts a prior quote and returns an async entity to poll until completion.\nFor commercial execute calls, the target domain is\nexpressed in the request body, not the path. Sub-resources (`contacts`,\n`nameservers`, `privacy`, `auto-renew`, `transfer-lock`, `records`) only exist\nin the context of a specific domain-name instance. The `/check-availability`\ncontroller accepts GET (single domain) or POST (1–25 domains) and carries no\npersistent identity.\n\n**Flat, two-level maximum.** No resource path goes deeper than\n`/{collection}/{id}/{sub-resource}` or `/{collection}/{id}/{sub-collection}/{id}`.\n\n**Reseller on-behalf-of.** Resellers pass `X-Shopper-Id`; all operations are\nthen scoped to that shopper. Absent the header, the authenticated entity's own\naccount is used.\n\n## Launch Scope (v3.0)\nStandard TLDs only. TLDs with eligibility requirements (.us, .ca, .eu) return\n`UNSUPPORTED_TLD` until Phase 2.\n",
"title": "Domain Lifecycle Management API",
"version": "3.2.0",
"version": "3.3.0",
"x-visibility": "public"
},
"openapi": "3.0.3",
Expand Down Expand Up @@ -4022,6 +4100,20 @@
"ttl": 3600,
"type": "MX"
}
},
"tlsaRecord": {
"summary": "Create a TLSA record (DANE-EE SHA-256 SPKI pin for HTTPS on port 443)",
"value": {
"certificateData": "d2abde240d7cd3ee6b4b28c54df034b97983a1d16e8a410e4561cb106618e971",
"matchingType": 1,
"name": "www",
"port": 443,
"protocol": "_tcp",
"selector": 1,
"ttl": 3600,
"type": "TLSA",
"usage": 3
}
}
},
"schema": {
Expand Down
8 changes: 6 additions & 2 deletions rust/domains-client/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -471,7 +471,11 @@ mod tests {
.create_dns_record()
.zone("example.com")
.body(types::DnsRecord {
data: "1.2.3.4".to_string(),
certificate_data: None,
matching_type: None,
selector: None,
usage: None,
data: Some("1.2.3.4".to_string()),
flag: None,
name: "www".to_string(),
parameters: None,
Expand Down Expand Up @@ -601,7 +605,7 @@ mod tests {
let items = body.items.expect("items present");
assert_eq!(items.len(), 1);
assert_eq!(items[0].record_id.as_deref(), Some("rec-1"));
assert_eq!(items[0].data, "1.2.3.4");
assert_eq!(items[0].data.as_deref(), Some("1.2.3.4"));
}

#[tokio::test]
Expand Down
Loading
Loading