Improve API path consistency and discoverability #6

New issue

Open

opened 2026-05-03 06:21:56 +00:00 by lambadalambda · 0 comments

lambadalambda commented

2026-05-03 06:21:56 +00:00

Owner

Problem

The API was harder to use than expected while debugging pipelines.

Issues encountered:

Pipeline endpoints use pipeline number in some places, but it is easy to confuse with pipeline id.
Guessed log paths returned the frontend SPA HTML with HTTP 200 rather than a JSON API error, making mistakes look like successful responses.
The useful log endpoint was /api/repos/{repo_id}/logs/{pipeline_number}/{step_id}, but it was not easy to discover from the UI/debugging context.
/api/version did not return useful version JSON in our deployment path; it returned frontend HTML.

Desired behavior

Improve API consistency and errors:

clearly distinguish pipeline id vs pipeline number in docs and response fields
include canonical log URLs in pipeline/workflow/step API responses
return JSON 404/405 for unknown /api paths instead of SPA HTML
expose a stable documented version endpoint under the API prefix or link to the correct endpoint

Why this matters

Operators rely on the API during CI incidents. HTML fallback responses and id/number ambiguity slow down debugging and automation.

## Problem The API was harder to use than expected while debugging pipelines. Issues encountered: - Pipeline endpoints use pipeline number in some places, but it is easy to confuse with pipeline id. - Guessed log paths returned the frontend SPA HTML with HTTP 200 rather than a JSON API error, making mistakes look like successful responses. - The useful log endpoint was /api/repos/{repo_id}/logs/{pipeline_number}/{step_id}, but it was not easy to discover from the UI/debugging context. - /api/version did not return useful version JSON in our deployment path; it returned frontend HTML. ## Desired behavior Improve API consistency and errors: - clearly distinguish pipeline id vs pipeline number in docs and response fields - include canonical log URLs in pipeline/workflow/step API responses - return JSON 404/405 for unknown /api paths instead of SPA HTML - expose a stable documented version endpoint under the API prefix or link to the correct endpoint ## Why this matters Operators rely on the API during CI incidents. HTML fallback responses and id/number ambiguity slow down debugging and automation.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

pleroma/woodpecker#6

No description provided.

Rows
Columns