Design a listing connectivity ingestion service

Scenario

You are designing a Connectivity Service that allows external service providers (partners) to create or update listings in your company’s platform.

Partners send listing-creation requests to your service. Your service must forward the listing data to an internal downstream system (the Validation / Domain Service) owned by another team for validation and domain processing. After validation, your service must return a result to the partner.

The interview expects a very detailed REST API specification (endpoints, request/response payloads, headers, authentication, idempotency) and a clear end-to-end flow diagram.

Requirements

Functional

• Accept listing create/update requests from external partners.
• Validate basic request correctness at the edge (schema, auth, size limits).
• Send the request to an internal Validation/Domain Service for business validation.
• Return a clear outcome to the partner:
  • Accepted/created
  • Rejected with validation errors
  • Still processing (if async)
• Support retries safely (no duplicate listings).

API / Protocol expectations

• Use HTTP with JSON payloads.
• Specify:
  • Required headers (e.g., Content-Type , tracing/correlation)
  • Authentication/authorization mechanism
  • Idempotency strategy
  • Possible HTTP status codes and when each applies

Non-functional

• Must scale to high request volume and multiple partners.
• Be resilient to partner retries and downstream Validation Service outages/latency.
• Provide observability (metrics/logs/tracing) and auditability.

Deliverables

1. A proposed API design (endpoints + request/response examples + headers).
2. A sequence/flow description (textual flow diagram is OK).
3. Notes on scaling, reliability, and key edge cases.