National Addressing System

Ministry of Housing and Urban Planning in the Sultanate of Oman

User Tools

Site Tools

You are here: start » reference » system-architecture » address-editing-and-query-api
reference:system-architecture:address-editing-and-query-api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
reference:system-architecture:address-editing-and-query-api [2025/08/26 21:34] – [NAS Address Editing and Query API Specification] runarbereference:system-architecture:address-editing-and-query-api [2025/08/27 06:33] (current) – runarbe
Line 1: Line 1:
-====== NAS Address Editing and Query API Specification ======+====== Address Editing and Query API ====== 
 + 
 +This API provides methods to interact with the core addressing data model such as creating, reading, updating and deleting address objects as well as querying them and keeping them in sync with application data and external copies/cached data.
  
 ===== 1. Integration with Third-Party GIS Platforms ===== ===== 1. Integration with Third-Party GIS Platforms =====
  
-The APIsupports integration with several third-party Geographic Information System (GIS) platforms via standard open protocols:+The API supports integration with several third-party Geographic Information System (GIS) platforms via standard open protocols:
  
-  * +  * GeoServer: Supports WFS, WMS, and GeoAPI. 
- +  * (ArcGIS Enterprise: Utilises the ArcGIS REST API)
-GeoServer: Supports WFS, WMS, and GeoAPI. +
- +
-  * +
- +
-(ArcGIS Enterprise: Utilises the ArcGIS REST API)+
  
 ===== 2. Suitable technologies for implementing API ===== ===== 2. Suitable technologies for implementing API =====
Line 17: Line 14:
 Selecting the right technologies is crucial for efficient APIimplementation. Two primary technologies are recommended: Selecting the right technologies is crucial for efficient APIimplementation. Two primary technologies are recommended:
  
-  *+  * Microsoft .NET Core: This framework is selected for its compatibility with the organisation’s software environment. It provides high performance and operates as a lower-level language, though it is marginally more complex. 
 +  * Python: Known as the universal language for data scientists, Python integrates smoothly with GIS platforms. ArcGIS utilises Python for analytics and extensions, making it a preferred choice for GIS programmers. Its use within the Microsoft platform further encourages its adoption.
  
-Microsoft .NET Core: This framework is selected for its compatibility with the organisation’s software environment. It provides high performance and operates as a lower-level language, though it is marginally more complex. +===== 3. Technical requirements =====
- +
-  * +
- +
-Python: Known as the universal language for data scientists, Python integrates smoothly with GIS platforms. ArcGIS utilises Python for analytics and extensions, making it a preferred choice for GIS programmers. Its use within the Microsoft platform further encourages its adoption. +
- +
- +
-===== 1. RESTful API ===== +
- +
-Types of actions in a REST API +
- +
-  * HttpGet: This method is used to retrieve and query records from the database. +
-  * HttpPut: This function updates existing records. +
-  * HttpPost: Utilised for creating new entries in the database. +
-  * HttpDelete: This method deletes records currently stored. +
- +
-For each data type, a unique controller oversees these actions, ensuring a structured and coherent data handling process. The API is designed to be user-friendly, adhere to industry standards, and is thoroughly documented. +
- +
-===== 2. Technical approach =====+
  
 From the outset, the technical approach involves utilising: From the outset, the technical approach involves utilising:
Line 44: Line 24:
   * Python >= 3.12: The latest iteration of the Python programming language.   * Python >= 3.12: The latest iteration of the Python programming language.
   * Containerization using Docker: The leading technology for containerization of server applications   * Containerization using Docker: The leading technology for containerization of server applications
- +  * Linux operating system: A robust and proven platform for hosting services.
-Linux operating system: A robust and proven platform for hosting services.+
  
 This structure aims to enhance the National Addressing System's functionality, supporting accurate and efficient data management and integration across various platforms. This structure aims to enhance the National Addressing System's functionality, supporting accurate and efficient data management and integration across various platforms.
  
-==== 2.1 Performance Management, Rate Limiting, Caching, and Developer Enablement ====+==== 3.1 Performance Management, Rate Limiting, Caching, and Developer Enablement ====
  
 To ensure reliable, scalable, and fair access to the NAS API ecosystem—particularly as integrations expand to include both public and private third-party systems—the platform should adopt additional operational controls and developer support mechanisms: To ensure reliable, scalable, and fair access to the NAS API ecosystem—particularly as integrations expand to include both public and private third-party systems—the platform should adopt additional operational controls and developer support mechanisms:
  
-==== 2.2 Rate Limiting and Caching ====+==== 3.2 Rate Limiting and Caching ====
  
 The NAS API layer will benefit from the implementation of rate limiting to prevent abuse, ensure equitable resource allocation, and protect backend systems from overload during periods of high demand. Rate limiting policies will be clearly defined in API documentation and enforced per API client or token, with the flexibility to grant higher limits to critical government and infrastructure partners. The NAS API layer will benefit from the implementation of rate limiting to prevent abuse, ensure equitable resource allocation, and protect backend systems from overload during periods of high demand. Rate limiting policies will be clearly defined in API documentation and enforced per API client or token, with the flexibility to grant higher limits to critical government and infrastructure partners.
Line 59: Line 38:
 Complementing rate limiting, API-level caching mechanisms (e.g., in-memory caches, reverse proxies, or CDN-based edge caching) will be deployed to accelerate the most frequently accessed data and reduce repeated queries to the primary database. Caching strategies will be tailored according to data volatility and use-case, balancing data freshness against system responsiveness. Complementing rate limiting, API-level caching mechanisms (e.g., in-memory caches, reverse proxies, or CDN-based edge caching) will be deployed to accelerate the most frequently accessed data and reduce repeated queries to the primary database. Caching strategies will be tailored according to data volatility and use-case, balancing data freshness against system responsiveness.
  
-==== 2.3 Service Level Agreements (SLAs) for Integrations ====+==== 3.3 Service Level Agreements (SLAs) for Integrations ====
  
 For all external integrations, especially those with business-critical third-party systems, formal Service Level Agreements (SLAs) will be established. SLAs will define key parameters such as guaranteed uptime, target response times, maintenance notification windows, and escalation procedures for incidents. This transparency fosters trust among stakeholders and ensure predictable quality of service for mission-critical operations. For all external integrations, especially those with business-critical third-party systems, formal Service Level Agreements (SLAs) will be established. SLAs will define key parameters such as guaranteed uptime, target response times, maintenance notification windows, and escalation procedures for incidents. This transparency fosters trust among stakeholders and ensure predictable quality of service for mission-critical operations.
  
-==== 2.4 Performance Benchmarks and Scalability Thresholds ====+==== 3.4 Performance Benchmarks and Scalability Thresholds ====
  
 To guide system sizing and support future growth, the NAS API and underlying infrastructure will be subject to regular performance benchmarking. Metrics such as average and 95th percentile response times, throughput under load, and maximum supported concurrent connections will be documented. Scalability thresholds (e.g., API requests per minute, data volume limits, user concurrency) will be specified and reviewed as usage patterns evolve. To guide system sizing and support future growth, the NAS API and underlying infrastructure will be subject to regular performance benchmarking. Metrics such as average and 95th percentile response times, throughput under load, and maximum supported concurrent connections will be documented. Scalability thresholds (e.g., API requests per minute, data volume limits, user concurrency) will be specified and reviewed as usage patterns evolve.
  
-==== 2.5 Sandbox Environments for Integration Testing ====+==== 3.5 Sandbox Environments for Integration Testing ====
  
 To facilitate secure and efficient onboarding of new integrators, a sandbox environment—mirroring the production API but operating on test data—will be provided to registered developers. This environment enables third parties to prototype and validate their integrations without risk to production data or services. Comprehensive API documentation, test credentials, and sample data will be made available within the sandbox to accelerate development and troubleshooting. To facilitate secure and efficient onboarding of new integrators, a sandbox environment—mirroring the production API but operating on test data—will be provided to registered developers. This environment enables third parties to prototype and validate their integrations without risk to production data or services. Comprehensive API documentation, test credentials, and sample data will be made available within the sandbox to accelerate development and troubleshooting.
  
-===== 3 API methods specification =====+===== 4 Required API methods =====
  
 The API must as minimum implement the following methods. Authentication is exempt but implicitly required for acceptable system operations. The API must as minimum implement the following methods. Authentication is exempt but implicitly required for acceptable system operations.
  
-^_PARA__TABLE_INS_Tag^_PARA__TABLE_INS_Method^_PARA__TABLE_INS_Endpoint^_PARA__TABLE_INS_Description| | +^ \\ Tag^ \\ Method^ \\ Endpoint^ \\ Description| | 
-|_PARA__TABLE_INS_**address-unit** |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/address-unit/read-all|_PARA__TABLE_INS_Read all address units| | +| \\ **address-unit** | \\ GET| \\ /address-unit/read-all| \\ Read all address units| | 
-| |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/address-unit/read/{adrutid}|_PARA__TABLE_INS_Read one address unit| | +| | \\ GET| \\ /address-unit/read/{adrutid}| \\ Read one address unit| | 
-| |_PARA__TABLE_INS_POST|_PARA__TABLE_INS_/address-unit/upsert|_PARA__TABLE_INS_Insert or update an address unit| | +| | \\ POST| \\ /address-unit/upsert| \\ Insert or update an address unit| | 
-| |_PARA__TABLE_INS_DELETE|_PARA__TABLE_INS_/address-unit/delete/{adrutid}|_PARA__TABLE_INS_Delete an address unit| |+| | \\ DELETE| \\ /address-unit/delete/{adrutid}| \\ Delete an address unit| |
 | |POST|/address-unit/sync|Synchronise uploaded dataset with server| | | |POST|/address-unit/sync|Synchronise uploaded dataset with server| |
 | | | | | | | | | | | |
-|_PARA__TABLE_INS_**sub-address** |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/sub-address/read-all|_PARA__TABLE_INS_Read all sub-addresses| | +| \\ **sub-address** | \\ GET| \\ /sub-address/read-all| \\ Read all sub-addresses| | 
-| |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/sub-address/read/{adrutid}|_PARA__TABLE_INS_Read one sub-address| | +| | \\ GET| \\ /sub-address/read/{adrutid}| \\ Read one sub-address| | 
-| |_PARA__TABLE_INS_POST|_PARA__TABLE_INS_/sub-address/upsert|_PARA__TABLE_INS_Insert or update a sub-address| | +| | \\ POST| \\ /sub-address/upsert| \\ Insert or update a sub-address| | 
-| |_PARA__TABLE_INS_DELETE|_PARA__TABLE_INS_/sub-address/delete/{adrutid}|_PARA__TABLE_INS_Delete a sub-address| |+| | \\ DELETE| \\ /sub-address/delete/{adrutid}| \\ Delete a sub-address| |
 | |POST|/sub-address/sync|Synchronise uploaded dataset with server| | | |POST|/sub-address/sync|Synchronise uploaded dataset with server| |
 | | | | | | | | | | | |
-|_PARA__TABLE_INS_**street** |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/street/read-all|_PARA__TABLE_INS_Read all streets| | +| \\ **street** | \\ GET| \\ /street/read-all| \\ Read all streets| | 
-| |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/street/read/{adrutid}|_PARA__TABLE_INS_Read one street| | +| | \\ GET| \\ /street/read/{adrutid}| \\ Read one street| | 
-| |_PARA__TABLE_INS_POST|_PARA__TABLE_INS_/street/upsert|_PARA__TABLE_INS_Insert or update a street| | +| | \\ POST| \\ /street/upsert| \\ Insert or update a street| | 
-| |_PARA__TABLE_INS_DELETE|_PARA__TABLE_INS_/street/delete/{adrutid}|_PARA__TABLE_INS_Delete a street| |+| | \\ DELETE| \\ /street/delete/{adrutid}| \\ Delete a street| |
 | |POST|/street/sync|Synchronise uploaded dataset with server| | | |POST|/street/sync|Synchronise uploaded dataset with server| |
 | | | | | | | | | | | |
-|_PARA__TABLE_INS_**street-segment** |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/street-segment/read-all|_PARA__TABLE_INS_Read all street segments| | +| \\ **street-segment** | \\ GET| \\ /street-segment/read-all| \\ Read all street segments| | 
-| |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/street-segment/read/{adrutid}|_PARA__TABLE_INS_Read one street segment| | +| | \\ GET| \\ /street-segment/read/{adrutid}| \\ Read one street segment| | 
-| |_PARA__TABLE_INS_POST|_PARA__TABLE_INS_/street-segment/upsert|_PARA__TABLE_INS_Insert or update a street segment| | +| | \\ POST| \\ /street-segment/upsert| \\ Insert or update a street segment| | 
-| |_PARA__TABLE_INS_DELETE|_PARA__TABLE_INS_/street-segment/delete/{adrutid}|_PARA__TABLE_INS_Delete a street segment| |+| | \\ DELETE| \\ /street-segment/delete/{adrutid}| \\ Delete a street segment| |
 | |POST|/street-segment/sync|Synchronise uploaded dataset with server| | | |POST|/street-segment/sync|Synchronise uploaded dataset with server| |
 | | | | | | | | | | | |
-|_PARA__TABLE_INS_**issues** |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/issues/read-all|_PARA__TABLE_INS_Read all issues| | +| \\ **issues** | \\ GET| \\ /issues/read-all| \\ Read all issues| | 
-| |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/issues/read/{adrutid}|_PARA__TABLE_INS_Read one issue| | +| | \\ GET| \\ /issues/read/{adrutid}| \\ Read one issue| | 
-| |_PARA__TABLE_INS_POST|_PARA__TABLE_INS_/issues/upsert|_PARA__TABLE_INS_Insert or update an issue| | +| | \\ POST| \\ /issues/upsert| \\ Insert or update an issue| | 
-| |_PARA__TABLE_INS_DELETE|_PARA__TABLE_INS_/issues/delete/{adrutid}|_PARA__TABLE_INS_Delete an issue| |+| | \\ DELETE| \\ /issues/delete/{adrutid}| \\ Delete an issue| |
 | |POST|/issues/sync|Synchronise uploaded dataset with server| | | |POST|/issues/sync|Synchronise uploaded dataset with server| |
 | | | | | | | | | | | |
-|_PARA__TABLE_INS_**start-stop** |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/start-stop/read-all|_PARA__TABLE_INS_Read all start-stop points| | +| \\ **start-stop** | \\ GET| \\ /start-stop/read-all| \\ Read all start-stop points| | 
-| |_PARA__TABLE_INS_GET|_PARA__TABLE_INS_/start-stop/read/{adrutid}|_PARA__TABLE_INS_Read one start-stop point| | +| | \\ GET| \\ /start-stop/read/{adrutid}| \\ Read one start-stop point| | 
-| |_PARA__TABLE_INS_POST|_PARA__TABLE_INS_/start-stop/upsert|_PARA__TABLE_INS_Insert or update a start-stop point| | +| | \\ POST| \\ /start-stop/upsert| \\ Insert or update a start-stop point| | 
-| |_PARA__TABLE_INS_DELETE|_PARA__TABLE_INS_/start-stop/delete/{adrutid}|_PARA__TABLE_INS_Delete a start-stop point| |+| | \\ DELETE| \\ /start-stop/delete/{adrutid}| \\ Delete a start-stop point| |
 | |POST|/start-stop/sync|Synchronise uploaded dataset with server| | | |POST|/start-stop/sync|Synchronise uploaded dataset with server| |
 |**query** | | | | | |**query** | | | | |
reference/system-architecture/address-editing-and-query-api.1756244040.txt.gz · Last modified: by runarbe