Application brief

Responsibilities and boundaries

The monitor store and retry worker are internal BFF implementation concerns. The Order API and Kafka broker are external dependencies and must be replaceable with test doubles through configuration. Implementing the Order API, Kafka consumers, or a product database is out of scope.

GET /health - application readiness

Return 200 application/json once the HTTP application is initialized and ready to accept requests. The response body must be exactly:

{
  “status”: “UP”
}

This is a shallow application-readiness check. It must not call the Order API or Kafka, inspect or mutate monitor state, publish messages, or perform other business side effects. Dependency readiness is managed separately by the runtime and test harness.

Shared data shapes

ProductBase is a JSON object with the following fields:

Example:

{
  “name”: “iPhone”,
  “type”: “gadget”,
  “inventory”: 100
}

Product contains every ProductBase field plus the following fields:

Example:

{
  “id”: 1,
  “name”: “iPhone”,
  “type”: “gadget”,
  “inventory”: 100,
  “createdOn”: “2025-01-01”
}

An error response is an application/json object with the following fields:

Example:

{
  “timestamp”: “2025-01-01T10:15:30Z”,
  “status”: 400,
  “error”: “Bad Request”,
  “message”: “Request validation failed”
}

POST /products - create a product

Accept a required Content-Type: application/json request body matching ProductBase.

Example request:

```http POST /products HTTP/1.1 Content-Type: application/json

{ “name”: “iPhone”, “type”: “gadget”, “inventory”: 100 } ```

Allowed responses:

The Link header must match this exact structure, with a numeric monitor ID and an alphanumeric, space, underscore, or hyphen title:

Link: </monitor/123>;rel=related;title=monitor

GET /monitor/{id} - retrieve a deferred request

id is a required integer path parameter.

Allowed responses:

A monitor object has the following fields:

A recorded request has the following fields:

A recorded response has the following fields:

A header item has the following fields:

Completed-monitor example:

{
  “request”: {
    “method”: “POST”,
    “body”: {
      “name”: “iPhone”,
      “type”: “gadget”,
      “inventory”: 100
    },
    “headers”: []
  },
  “response”: {
    “statusCode”: 201,
    “body”: {
      “id”: 1
    },
    “headers”: []
  }
}

Before the retry completes, return the recorded request and omit the unavailable response. Once the retry succeeds, retain the response so subsequent monitor calls return both objects.

GET /findAvailableProducts - find available products

Request inputs:

Example request:

GET /findAvailableProducts?type=gadget&from-date=2025-01-01&to-date=2025-11-28 HTTP/1.1
pageSize: 10

Allowed responses:

Example successful response:

[
  {
    “id”: 1,
    “name”: “iPhone”,
    “type”: “gadget”,
    “inventory”: 100,
    “createdOn”: “2025-01-01”
  }
]

Downstream GET /products

The downstream endpoint accepts the same optional type query parameter, optional pageSize integer header, and optional from-date and to-date date query parameters described above. A successful response is 200 application/json with an array of Product objects. A bad request is 400 application/json with the error shape described above.

Example interaction:

GET /products?type=gadget&from-date=2025-01-01&to-date=2025-11-28 HTTP/1.1
pageSize: 10

```http HTTP/1.1 200 OK Content-Type: application/json

[ { “id”: 1, “name”: “iPhone”, “type”: “gadget”, “inventory”: 100, “createdOn”: “2025-01-01” } ] ```

Downstream POST /products

Send an application/jsonProductBase body. The downstream call requires:

• a non-empty Authenticate API-key header; and
• an Idempotency-Key header containing a UUID so retries do not create duplicates.

On success, it returns 201 application/json with an object containing required integer field id. It can also return 400 Bad Request, 415 Unsupported Media Type, or 422 Unprocessable Entity, each with an application/json error body.

Example interaction:

```http POST /products HTTP/1.1 Content-Type: application/json Authenticate: configured-api-key Idempotency-Key: 3d593d8d-6141-4c13-aad1-d0bc2f20ca42

{ “name”: “iPhone”, “type”: “gadget”, “inventory”: 100 } ```

```http HTTP/1.1 201 Created Content-Type: application/json

{ “id”: 1 } ```

Deferred POST processing

• When the downstream POST times out, return 202, record the request, and provide its monitor URL in the Link header.
• Retry the same downstream request in a background thread pool every 1 second until it succeeds or 10 retries have been attempted.
• Reuse the same idempotency key for every retry of one logical product-creation request.
• When a retry succeeds, record the downstream response so the next monitor call returns the request and response.

GET throttling

• When the downstream GET times out, return 429 with Retry-After: 1, and enforce the one-second retry interval.
• When the downstream GET fails because the Order API is unreachable, including connection refusal, DNS failure, or connection reset, return the documented 503 Service Unavailable error response.
• A later successful request follows the normal 200 response and Kafka publication flow.

Downstream response validation

• When type was supplied, every returned product must have exactly that type.
• When from-date was supplied, every returned product’s createdOn date must be on or after it.
• When to-date was supplied, every returned product’s createdOn date must be on or before it.
• Return the documented 502 error response if any returned product violates these conditions. Do not publish a Kafka message for an invalid downstream response.