reference:system-architecture:address-integration-api
Table of Contents
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