Development and Technical direction
Here you will find all the information needed to develop software in collaboration with Digital Iceland. Technical direction contains information about the structure, programming tools, work processes, etc.
Table of contents
Technical direction
Digital Iceland’s Technical Direction has a detailed description of architectural patterns, development tools, workflows and values that should be adopted by teams building solutions for Ísland.is.
Developer handbook
The developer handbook contains documentation, processes, and guidelines for the development software process for Digital Iceland. The Ísland.is software is developed by technical teams from many suppliers and organisations, the Code Library is open.
All new developers should get familiar with the following documentation:
An overview of the tools and techniques we use.
Instruction for automatic code generation for web service communication.
How to create automatic end to end tests.
Get access to development secrets and development services.
Instructions on how to generate new projects.
Information about project management and quality control.
You can access development guidelines for the main projects of Ísland.is here:
Following documentation in the development handbook could also be useful for organizations:
Web services policy
Data communication through web services is a prerequisite for digital solutions and is therefore necessary to improve government services for individuals and businesses.
Organizations should therefore consider implementing web services on top of the data they are responsible for. They should also consider how to increase automation by using web services from others.
A number of web services are available through the x-road Service catalog.
X-road
X-road is an open data transfer layer that allows organizations to exchange information over the Internet. X-Road is a centrally managed distributed Data Exchange Layer between information systems. Organizations can exchange information over the Internet using X-Road to ensure confidentiality, integrity and interoperability between data exchange parties.
X-road supports service providers to access control their own web services, as well as accessing web services of others. Access can be provided for entire web services or for specific endpoints.
For setting up x-road security server, you need to apply through an application. More technical information can be found in the development handbook.
Design of web services
We recommend that organizations implement web services using a "RESTful" architecture based on simple HTTP and JSON queries. Digital Iceland publishes API design guide, which contains recommendations on naming conventions, data types, error handling, documentation, version controls, and much more.
It is highly recommended to document web services with OpenAPI (Swagger). It simplifies the registrations of the web service in X-road, and will become available in the service catalog. The documentation is particularly useful for developers implementing the web service, but OpenAPI documentation allows for automatic generation of implementation code in most development environments.
When it comes to version control, it is important not to introduce breaking changes to the web services that have been released to the production environment. Changes to endpoints or attributes that are not backward compatible must be published in a new version of the web service on a new URL.
More information can be found in the API design guide.
Authentication and access control
Access control of web services can be done in many ways, but this depends mainly on how systems will call the web services and the nature of the data the web service returns.
If the web service only requires machine-to-machine authentication, X-road is a very good solution. If X-road is the only access control for the web service, communication should be encrypted end to end with HTTPS and Mutual TLS (mTLS).
Another option is to implement system authentication with access tokens. The query system calls in a central authentication server with client credentials and receives an access token back that is sent with the requests to the web service. The Island.is Authentication system supports system authentication.
If the web service is also intended to identify end users, e.g. to manage access to sensitive information, it is best to use access tokens from the island.is Authentication system. In this way, queries can be traced down to end users who are truly authorized with electronic identification. Similarly, this access control offers delegation (parents, power of attorney, etc.) and consent.
We recommend using both access tokens and x-road to protect web services.
Access to Web Services
To access web services in X-road, you must contact the owner of the web service.
Access to web services is managed through an X-road admin system. The owner of the web service manages access to their own web services and decides to whom they give access, other organizations or companies. It is good to know that to be able to exchange data through x-road, both parties, the one that is providing data and the consumer of the data, need to have x-road security server setup.