OpenConceptLab/ocl_issues#2881 | Export API and Subscriptions: POST/DELETE responses, download steps

[paynejd]

Closes OpenConceptLab/ocl_issues#2881

Follows #68 (merged), which it builds on.

oclapi/apireference/exportapi.md

• Overview: is_processing turning False doesn't mean an export exists, because the flag is cleared even when the export fails. The page now says to use the Export API to check.

• POST: the response codes now match ConceptContainerExportMixin.post:

  • 202 when an export is started;
  • 208 while an export is being created;
  • 409 only when the same job is already queued;
  • 303 with a URL header when the export exists, or 204 with noRedirect=true.

  force=true (create the export again) is now documented.

• DELETE: the example is captioned "Delete", not "Create". The status labels are now 204 No Content and 404 Not Found, and the 403 for users without admin access is listed.

oclapi/apireference/other/subscriptions.md

• The export GET redirects (302, Location header) to a signed URL that expires. It doesn't return an exportURL/exportUrl header, and the URL isn't single-use.
• The file is a zip, not a compressed tar.
• The page now shows converting the filename's lastUpdated (2026-09-30_123456) to ISO 8601 (2026-09-30T12:34:56Z) for updatedSince.

🤖 Generated with Claude Code

[paynejd]

Codex adversarial review, pass 1 (codex-cli 0.160.1, commit 7b78512)

Run locally before the branch could be pushed. The oclapi2 links point to the OpenConceptLab/oclapi2#929 branch.

Found four issues in the changed lines, including retained inaccuracies:

1. [P2] DELETE does not always remove the downloadable export — exportapi.md:163. GET selects the cached key using get_export_path(), but DELETE removes version.version_export_path, computed from the current timestamp. If the cached key has an older timestamp or legacy format, DELETE can return 204 while leaving it downloadable. This is a pre-existing backend limitation; qualify the deletion guarantee. See mixins.py:1114 and models.py:1399.

2. [P2] Retrying GET cannot recover a missing export — subscriptions.md:22. The instructions group 204 and 208 together as conditions resolved by waiting. After an export fails or is deleted, repeated GETs can return 204 indefinitely: GET never schedules creation. Explain that a persistently missing export, with no pending creation work, requires POST to initiate creation before polling. See mixins.py:1048.

3. [P3] The noRedirect response condition omits precedence — exportapi.md:139. An existing export plus noRedirect=true does not necessarily return 204: adding force=true takes the creation branch (202 or 409), and an active export takes precedence over both flags (208). Qualify the 303/204 cases as applying when no export is running and force is disabled. See mixins.py:1085.

4. [P3] The unconditional speed advantage is unsupported — exportapi.md:4. “It is also faster” is not guaranteed by the implementation. Version seeding queues the export after other processing steps, and collection exports wait for expansion processing. Keep the reliability rationale; remove or qualify the performance claim. See tasks.py:442 and tasks.py:156.

Ran the requested diff and checked the specified implementation. In-memory branch checks confirmed findings 1–3; no files were modified.

Overall verdict: changes requested. No P0 or P1 findings.

[paynejd]

Replies to Codex pass 1. All four are fixed in 0daea32:

1. DELETE can leave an older export (fixed in the docs): a new DELETE note says it removes only the export cached under the version's current lastUpdated, and that an export under an earlier timestamp stays downloadable. The backend fix belongs in oclapi2: DELETE should remove the key that GET serves (get_export_path()). That's outside this docs ticket.
2. A 204 needs a POST (fixed): subscriptions.md now says 208 means wait and request again, and 204 means no export exists, so the client must POST to create one first.
3. POST precedence (fixed): the response list now begins with the order of the checks. 208 wins over force and noRedirect, and force=true wins over noRedirect.
4. Speed claim (fixed): removed.

[paynejd]

Codex adversarial review, pass 2 (codex-cli 0.160.1, commit 0daea32)

• [P2] The 303 follow-up instruction fails for HEAD exports — docs/source/oclapi/apireference/exportapi.md:134. For an existing HEAD export, POST returns URL: /orgs/OWNER/sources/REPO/export/, omitting /HEAD/, because the implementation appends export/ to version.uri. That URL matches the version-detail route with version export, normally returning 404; collections behave identically. Thus “use GET there to download it” and the illustrated header are inaccurate for this supported case. Direct clients to GET the original explicit-version export endpoint and document the HEAD header limitation.

Overall verdict: Needs changes — one remaining P2 finding.

[paynejd]

Reply to Codex pass 2: HEAD export and the 303 URL header (fixed in 5cab8e9). Confirmed in oclapi2: for a HEAD export, POST builds the header as version.uri + 'export/', which leaves out HEAD/; oclapi2's own test asserts that value. The docs now tell clients to GET the same export URL they posted to, and say the header leaves out HEAD/ for HEAD exports. Making the header include HEAD/ would be an oclapi2 change, outside this docs ticket.

[paynejd]

Codex adversarial review, pass 3 (codex-cli 0.160.1, commit 5cab8e9)

No remaining or new [P0]–[P3] findings in the changed lines. Verified the requested diff against the specified implementation, including the HEAD export URL-header caveat. No files modified.

Overall verdict: Approve.