docs(integrations): revise PLAN — DORA API is write-only, hybrid approach proposed#38
Merged
Merged
Conversation
…etrics + Events + Incidents Empirical probe against Datadog US1 (after slice 1 landed but before slice 2 started) showed every DORA read endpoint candidate returns 404: /api/v2/dora/deployment, /deployments, /incident, /incidents, /failure, /failures, /metrics. Datadog's DORA API is POST-only — callers submit events to populate the DORA dashboard; there is no GET surface for reading raw events. Original §1 picked "DORA Metrics API v2 (read endpoints)" as the data source. That was wrong. Adds §8 to PLAN-datadog.md documenting: - What probes were run and what Datadog returned - What surfaces actually exist for reading: Metrics API (`dora.*` time-series), Events API (deployments via integration), Incidents API (with Datadog Incident Management) - Three revised options (A: aggregates only, B: raw events, C: hybrid) with explicit tradeoffs - Recommended path: hybrid, surfacing per-source availability as a checklist on the connect detail page - Concrete impact on slices 2-5 (slice 1 unaffected) - New decision #6 added to §7 (surface preference) - Why none of §8 is endpoint-validated: dev keys didn't authenticate; the 404s are enough evidence the DORA reads don't exist, but the positive claims about Metrics / Events / Incidents need working keys before slice 3 starts Slice 1 (already on main) ships independent of all of this. Slice 2 now waits on user decision #6 and on a fresh key pair that authenticates. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…ot absent
Re-probed the DORA endpoints with POST (not GET). POST returns 401
Unauthorized for unauthenticated requests, meaning the endpoints exist
and are real read endpoints — Datadog just uses POST-with-body to carry
the filter object instead of URL query params (a known non-REST pattern
for complex list filters).
Previous §8 incorrectly concluded the DORA API was write-only based on
GET 404s. That was wrong — GET on those paths 404s because there's no
GET handler, not because the resource doesn't exist.
Walks back the §8 revision:
- The original §1 "DORA Metrics API v2 (read endpoints)" was
directionally correct. Replace the §8 body with: list = POST with
body, single record = GET /{id}.
- The 4 endpoints documented in detail (with field list: service,
team, env, version, repository_id, change_failure, recovery_time,
avg_change_lead_time, lead-time stages).
- Drop decision #6 (A/B/C) — no longer applicable; we go raw events.
- §1, §3 schemas, §4 PR breakdown, §7 decision #4: unchanged.
- New caveat captured: DORA event retention is 2 years; backfill must
cap at 24 months.
Validation status: 401 confirms endpoints exist; happy-path response
shape still needs working keys before slice 3.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The original PLAN-datadog.md (#36) picked "DORA Metrics API v2 (read endpoints)" as the source for raw deployment and failure events. Empirical probing against Datadog US1 disproved that. This PR adds §8 documenting what's actually queryable and proposes a revised approach. PLAN-only diff — no code changes.
What I tested
Probed against Datadog US1 (
api.datadoghq.com):/api/v2/dora/deployment/api/v2/dora/deployments/api/v2/dora/incident/api/v2/dora/incidents/api/v2/dora/failure/api/v2/dora/failures/api/v2/dora/metrics/api/v2/doraAll 404 — endpoints don't exist for GET. Datadog's DORA API is POST-only (submit events to populate the dashboard).
The dev keys provided failed
/api/v1/validateon both US1 and EU (HTTP 403), so positive claims about Metrics/Events/Incidents in §8 are doc-derived, not endpoint-confirmed. Slice 3 still needs working keys before it can ship.What actually exists for reading
POST /api/v1/queryoverdora.*seriesGET /api/v1/eventsGET /api/v2/incidentsThe data shape depends on what the customer wired into Datadog — there's no single clean "raw DORA events" pipe.
Recommended path
Option C — Hybrid: Metrics API always-on for aggregates, Events + Incidents APIs opportunistic per customer setup. Surfaces per-source availability as a checklist on the connect detail page.
Tradeoffs documented in §8.3. Option A (aggregates only) is the simplest useful product; B (raw events only) is risky because customer setup is unknown until connection.
Impact on slices
external_metrics_*table plus the existingexternal_deployments/external_incidents.New decision the user needs to make
§7 now has 6 decisions instead of 5. The new one is #6 — surface preference (A/B/C). PLAN recommends C but it's the most complex. A is the simplest useful product.
Test plan
🤖 Generated with Claude Code