LogoLogo
  • Technical Direction
  • Technical overview
    • Technical Implementation
    • API Design Guide
      • Data Definitions and Standards
      • Data Transfer Objects
      • Documentation
      • Environments
      • Error Handling
      • Example API Service
      • GraphQL Naming Conventions
      • Methods
      • Naming Conventions
      • Once Only Principle
      • Pagination
      • Resource Oriented Design
      • REST Request
      • REST Response
      • Security
      • Versioning
    • Ísland.is Public Web Data Flow
    • Code Reviews
    • Code Standards
    • Monorepo
    • Project Management
    • Teamwork
    • Architectural Decision Records
      • Use Markdown Architectural Decision Records
      • Use NX
      • Continuous Integration
      • CSS
      • Branching and Release Strategy
      • Error Tracking and Monitoring
      • What API Management Tool to Consider
      • Viskuausan Static Site Generator
      • Use OAuth 2.0 and OpenID Connect As Protocols for Authentication and Authorization
      • Unified Naming Strategy for Files and Directories
      • CMS
      • Open Source License
      • What Chart Library Should We Use Across Island.is?
      • What Feature Flag Service/application Should We Use at Island.is?
      • Logging, Monitoring and APM Platform
      • ADR Template
    • Log Management Policy
  • Products
    • Island.is Authentication Service
      • Terminology
      • Integration Options
      • Authentication Flows
      • Authorising API Endpoints
      • Session Lifecycle
      • Scopes and Tokens
      • Delegations
      • Configuration
      • Tools and Examples
      • Environments
      • Test IAS with Postman
      • Using the IAS admin portal
    • Notifications / Hnipp
      • New Notification Setup Guide
      • Notifications service workflow overview
      • Email notifications
    • Pósthólfið
      • Security Checklist
      • Introduction
      • Skjalatilkynning API
      • Skjalaveita API
      • Sequence Diagram
      • Interfaces
    • Straumurinn (X-Road)
      • Architecture Guidelines for Service Providers and Consumers
      • Setting up an X-Road Security Server
        • Network Configuration
      • X-Road - Uppfærsla á öryggisþjónum
      • Straumurinn - Notkun og umsýsla
      • X-Road Central - current version
  • Development
    • Getting Started
    • Generating a New Project
    • Definition of done
    • Devops
      • Continuous Delivery
      • Database
      • Dockerizing
      • Environment Setup
      • Logging
      • Metrics
      • NextJS Custom Server
      • Observability
      • Operations Base Principles
      • Security
      • Service Configuration
      • Support
    • AWS Secrets
    • Feature Flags
    • Documentation Contributions
    • Defining Monorepo Boundaries With Tags
    • OpenAPI
    • Code Generation
    • Workspace Settings (Deprecated)
    • External Contributions
  • REFERENCE
    • Problems
      • 400 Validation Failed
      • 400 Attempt Failed
      • 403 Bad Subject
      • 400 500 Template API Error
    • Glossary
  • Misc
    • Guide: Adding a Payment Step to an Application
    • Guide: Enable Organisations to Make Requests to an Application
    • README Template
Powered by GitBook
On this page
  • Text encoding
  • JSON
  • National identifier
  • Language and currency
  • Date and time
  • Summary for date and time
  • Timestamp data

Was this helpful?

  1. Technical overview
  2. API Design Guide

Data Definitions and Standards

PreviousAPI Design GuideNextData Transfer Objects

Last updated 1 year ago

Was this helpful?

Text encoding

APIs should represent all texts in the encoding.

JSON

Primitive values MUST be serialized to JSON following the rules of and, as stated in the standard, JSON text MUST be encoded using UTF-8 .

JSON can represent four primitive types strings, numbers, booleans, and null and two structured types objects and arrays. Concepts like need to be represented using these types.

National identifier

Icelandic individuals are uniquely identified by a national identifier called kennitala. When referring to this identifier in URIs, requests, or responses, APIs should use the name nationalId. Its value is usually represented to users in the form ######-#### but APIs should use the form ########## at all times.

Language and currency

  • Languages - When specifying a language please use the (two letter) standard. See: .

  • Currencies - When specifying currency codes please use the standard. See: .

    • Amount - Use the format [0-9]+(.[0-9]+)? to represent an amount. Separate amount and currency in different fields. Example amount: 1250.23.

Date and time

Summary for date and time

Date and time should be represented as a string using the format yyyy-MM-ddThh:mm:ss.sssZ. Where

  • yyyy represents year, (four-digits).

  • MM represents month, (two-digits 01 - 12).

  • dd represents day of month, (two-digits 01 - 31).

  • hh represents hour, (two digits 00 - 23).

  • mm represents minute, (two digits 00 - 59).

  • ss represents second, (two digits 00 - 59).

  • sss represents a decimal fraction of a second, (one or more digits).

Examples:

Timestamp data

Date and time values should be represented in a string, as described in the proposed standard. The standard defines a profile of for use in Internet protocols. See: for Date/Time Format.

Z represents a time zone offset specified as Z (for ) or either + or - followed by a time expression hh:mm.

Icelandic local time can be represented with Z because Iceland follows the +00:00 all year round, which is the same as .

1985-04-12T23:20:50.52Z represents 20 minutes and 50.52 seconds after the 23rd hour of April 12th, 1985 in .

1996-12-19T16:39:57-08:00 represents 39 minutes and 57 seconds after the 16th hour of December 19th, 1996 with an offset of -08:00 from (Pacific Standard Time). Note that this is equivalent to 1996-12-20T00:39:57Z in UTC.

All returned data should contain the field createdTimestamp and it's value should be the when the data was created. This is important because of different caching rules and different viewpoints on when data should be considered obsolete.

RFC3339
ISO 8601
Section 5.6
UTC
UTC
GMT
UTC
UTC
UTF-8
RFC8259
RFC3629
ISO-639-1
639-1 codes
ISO-4217
4217 codes
Date and Time
date and time