National Addressing System

Ministry of Housing and Urban Planning in the Sultanate of Oman

User Tools

Site Tools


reference:system-architecture:address-integration-api

Integration framework Open API endpoint and documentation

To enable and foster external integrations with the addressing database from third party applications the national addressing system will offer a dedicated API for integrations.

Technical Requirements

  • Database Integration
  • The API may either:
  • Reuse the existing addressing database by adding a new schema, or
  • Operate on a dedicated database instance populated from the production data model.
  • An ETL (Extract, Transform, Load) procedure must be designed and implemented to populate the integration database and keep it continuously updated with changes from the production system.
  • Technology Stack
  • The API shall be implemented in either Python (FastAPI) or .NET Core, at the vendor’s discretion.
  • The design should prioritize modularity, maintainability, and alignment with modern development best practices (e.g., OpenAPI specification, REST principles, containerization readiness).
  • Performance and Scalability
  • The API must be dimensioned to handle high traffic volumes and frequent large queries without degradation of service.
  • Performance optimization measures (e.g., indexing, caching, query tuning, load balancing) should be included.
  • The solution should support horizontal scaling if required.
  • Security and Access Control
  • Authentication and authorization must be integrated with the existing OIDC identity provider.
  • The API should support self-registration workflows, either by directly consuming the OIDC registration API or by proxying it via a custom UI.
  • Data access must comply with agreed policies on privacy, data protection, and auditability.

Functional Requirements

The API must expose endpoints covering the following key use cases:

  • Bulk Data Access
    • Download the complete set of addressing data in structured formats suitable for third-party consumption.
  • Incremental Data Updates
    • Retrieve change sets for addressing data since a user-specified date/time.
    • Support for high-frequency incremental updates for near real-time synchronization.
  • Database Synchronization
    • Provide services to synchronize and mirror the central addressing database into decentralized instances.
    • Include retry and recovery mechanisms to ensure data consistency.
  • Search and Query Services
    • Free-text search across addressing records with relevance ranking.
    • Structured queries using address components (e.g., region, street, building).
  • Reference Data Access
    • Expose relevant code lists (e.g., administrative units, street types, address statuses) as web services.
  • Documentation and Developer Resources
    • Provide comprehensive API documentation following the Open API/Swagger standard.
    • Include tutorials, examples, and best practices for integration.
    • Contribute content for the Addressing Wiki, offering guidance for developers and integrators on how to use the API.

To be included in delivery

  • Fully functional and tested Integration Framework API.
  • ETL scripts/procedures to maintain synchronization between production and integration databases.
  • Open API specification file and interactive API documentation (Swagger UI or equivalent).
  • Developer documentation, tutorials, and content for the Addressing Wiki.
  • Deployment guidelines and system administration documentation.
  • Security and performance testing reports.
  • An addressing integration 101 example that describes all the steps involved to create an integration with the system
reference/system-architecture/address-integration-api.txt · Last modified: by runarbe