Skip to content

Standardize service-request result endpoints and with a PUT callback #262

Description

@lamurian

User Story

As a frontend and webhook integrator, I want a predictable and memorable REST endpoint to publish and retrieve asynchronous service results so that clients and webhook services can reliably exchange processing outcomes with clear semantics and minimal guesswork.

Description

The current async-result flow implemented in PR #237 uses multiple, non-intuitive endpoints:

  • POST [base]/api/v1/hook/service-name → returns serviceRequestId
  • GET [base]/api/v1/service-request/{serviceRequestId}/result → fetch result
  • POST [base]/api/v1/callback/service-request → webhook service updates result

These endpoints work, but the callback endpoint is inconsistent with the GET URL and not memorable. We need to standardize the API into:

  1. GET [base]/api/v1/service-request/{serviceRequestId} to fetch the result (removing /result from the existing path).
  2. PATCH [base]/api/v1/service-request/{serviceRequestId} to patch the result with the following update:
{
  "data": {
    "note": "Result after Webhook Service finishes processing",
    "authoredOn": "2025-11-01T08:05:10.614Z"
  }
}

The implementation must preserve security, idempotency, and observability.

Reference

  • Previous implementation PR: Feat/async service request #237
  • Legacy GET endpoint: GET [base]/api/v1/service-request/{serviceRequestId}/result
  • Legacy callback endpoint: POST [base]/api/v1/callback/service-request
  • The content of [base]/api/v1/service-request/{serviceRequestId}:
    {
      "success": true,
      "message": "success",
      "data": {
        "resourceType": "ServiceRequest",
        "status": "active",
        "intent": "order",
        "instantiatesUri": [
          "https://dev-api.konsulin.care/api/v1/hook/interpret"
        ],
        "subject": {
          "reference": "Group/guest"
        },
        "requester": {},
        "authoredOn": "2025-12-03T14:03:17.449568208Z",
        "note": "Result after Webhook Service finishes processing"
      }
    }

Notes:

  • Ensure that a GET request to [base]/api/v1/service-request/{serviceRequestId}/result is redirected to [base]/api/v1/service-request/{serviceRequestId}
  • Ensure the authoredOn in the PATCH request is required so the server can reason about ordering and avoid regressions from late-arriving callbacks.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    Status
    No status

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions