Internal API Contract for Address Search Connectors

This API defines the standard contract that all address search provider connectors must implement. The address-search-api service will call these endpoints to retrieve address data from the underlying provider (Regio, Loqate, etc.).

Implementation Notes:

• This is an internal service-to-service API (not exposed externally)
• Connectors must map provider-specific responses to this standard contract
• Connectors handle provider authentication, rate limiting, and error handling
• Connectors should cache results when appropriate to reduce provider API calls

Connector Responsibilities:

1. Authenticate with the provider (API keys, OAuth, etc.)
2. Transform search queries to provider-specific format
3. Map provider responses to standardised Plumery address model
4. Handle provider-specific errors and translate to standard error codes
5. Implement retry logic and circuit breakers for provider reliability

Architecture diagram