Skip to content

Clarify Exporting API response format and failure behavior#8438

Open
korthout wants to merge 2 commits intomainfrom
korthout-8435
Open

Clarify Exporting API response format and failure behavior#8438
korthout wants to merge 2 commits intomainfrom
korthout-8435

Conversation

@korthout
Copy link
Copy Markdown
Member

@korthout korthout commented Mar 31, 2026 •
edited
Loading

Description

  • Document that the Exporting API (pause/resume/soft-pause) always returns HTTP 200 and the actual result is in the response body's status field (204 = success, 500 = failure)
  • Add success and failure response examples to the management API docs
  • Document the topology precondition: the operation fails if any broker is unavailable
  • Add visible warnings in the backup guide so users don't need to expand collapsed blocks to learn about response checking

Changes applied consistently across all documented versions (8.6, 8.7, 8.8, next).

Closes #8435

New Management API
Screenshot 2026-03-31 at 18 09 35

New Backup guide
Screenshot 2026-03-31 at 18 09 16

When should this change go live?

  • This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
  • This is already available but undocumented and should be released within a week. (add available & undocumented label)
  • This is on a specific schedule and the assignee will coordinate a release with the Documentation team. (create draft PR and/or add hold label)
  • This is part of a scheduled alpha or minor. (add alpha or minor label)
  • There is no urgency with this change (add low prio label)

PR Checklist

  • My changes are for an upcoming minor release and are in the /docs directory (version 8.9).
  • My changes are for an already released minor and are in a /versioned_docs directory.

korthout and others added 2 commits March 31, 2026 17:36
@korthout @claude
Clarify Exporting API response format in management-api.md
31c4483 
The Exporting API always returns HTTP 200, but the actual result is
in the response body's status field (204 = success, 500 = failure).
This was undocumented, causing confusion for users who assumed the
HTTP status code indicated success.

Added:
- Note explaining HTTP 200 vs body status field behavior
- Success and failure response JSON examples
- Topology precondition (all brokers must be available)
- Updated tab descriptions to reference "status": 204

Applied consistently across all 4 documented versions (next, 8.8, 8.7, 8.6).

Addresses #8435

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@korthout @claude
Add response status warning to backup guide steps
b0d4776 
The backup guide's soft pause and resume steps show the exporting API
response in collapsed <details> blocks, making it easy to miss that
HTTP 200 doesn't mean success. Added visible :::warning admonitions
before these blocks so users see the status-checking guidance without
having to expand the example output.

Applied consistently across all 4 documented versions (next, 8.8, 8.7, 8.6).

Addresses #8435

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@korthout korthout added the deploy Stand up a temporary docs site with this PR label Mar 31, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 31, 2026

👋 🤖 🤔 Hello, @korthout! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.8/.

  • docs/self-managed/operational-guides/backup-restore/elasticsearch/backup.md
These files were changed only in versioned_docs/version-8.8/. You might want to duplicate these changes in docs/.
  • versioned_docs/version-8.8/self-managed/operational-guides/backup-restore/backup.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

@github-actions github-actions bot temporarily deployed to camunda-docs March 31, 2026 15:56 Destroyed
@korthout korthout added the kind/bug Issues related with bugs in the documentation label Mar 31, 2026
@korthout korthout marked this pull request as ready for review March 31, 2026 16:10
@korthout korthout requested review from a team March 31, 2026 16:11
@camunda-docs-pr-automation camunda-docs-pr-automation bot moved this to 👀 In Review in Documentation Team Mar 31, 2026
@korthout korthout added the support Issues related to support tickets label Mar 31, 2026
@github-actions github-actions bot temporarily deployed to camunda-docs March 31, 2026 16:25 Destroyed
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 31, 2026

The preview environment relating to the commit d1b2ef5 has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-8438/

fabiopaini-camunda
fabiopaini-camunda approved these changes Apr 1, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@fabiopaini-camunda fabiopaini-camunda left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thank you @korthout for this documentation improvement 👍

I see that the information is inside "Note" boxes in some places and "Warning" boxes in others, I'll defer to @camunda/tech-writers the decision on whether they are the right choice or not.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fabiopaini-camunda fabiopaini-camunda fabiopaini-camunda approved these changes

Assignees

@korthout korthout

Labels

deploy Stand up a temporary docs site with this PR kind/bug Issues related with bugs in the documentation support Issues related to support tickets

Projects

Documentation Team
Status: 👀 In Review

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: clarify exporting API response format and failure behavior

2 participants

@korthout @fabiopaini-camunda