What It Is
A National API Catalog is a centralized registry where government agencies publish machine-readable
API specifications for their digital services. Instead of humans navigating web portals to request services,
software systems discover, understand, and invoke services programmatically through standardized APIs.
Vision: Every public service—tax filing, business registration, health records, permits—becomes an API.
Third-party developers build citizen-facing apps, AI agents orchestrate multi-service workflows, and government systems
integrate seamlessly. "Government as a Platform."
This isn't just REST endpoints. It's a semantic API layer where:
- APIs are linked to data models (tietomallit.suomi.fi)
- Request/response schemas are machine-readable (OpenAPI, JSON Schema)
- Authentication is federated (OAuth 2.0, DID Auth)
- Rate limits and SLAs are transparent
Technical Architecture
Core Components
| Component |
Technology |
Purpose |
| API Registry |
OpenAPI 3.1 specs, AsyncAPI for events |
Centralized catalog of all government APIs |
| API Gateway |
Kong, Apigee, AWS API Gateway |
Routing, rate limiting, authentication, monitoring |
| Developer Portal |
Swagger UI, Redocly, custom React app |
Human-readable docs, sandbox environments, API keys |
| Identity Provider |
OAuth 2.0, OpenID Connect, DID Auth |
Authenticate API consumers (apps, agents, citizens) |
| Semantic Linker |
JSON-LD contexts, SHACL validators |
Link API schemas to national data models |
| Analytics Dashboard |
Grafana, ELK stack |
Track API usage, errors, performance metrics |
| SLA Monitor |
Prometheus, PagerDuty |
Alert on SLA breaches (uptime, latency) |
API Catalog Architecture
┌───────────────────────────────────────────────────────────────────┐
│ National API Catalog (api.suomi.fi) │
└───────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ API PROVIDERS (Agencies) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Tax Office │ │ DVV │ │ Kela │ │
│ │ (Vero API) │ │ (Pop. Reg) │ │ (Benefits) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ Publish │ Publish │ Publish │
│ │ OpenAPI │ OpenAPI │ OpenAPI │
└─────────┼───────────────────┼───────────────────┼─────────────────┘
│ │ │
└───────────────────┼───────────────────┘
│
┌─────────▼─────────┐
│ API Registry │
│ - OpenAPI specs │
│ - Semantic links │
│ - Rate limits │
│ - SLA terms │
└─────────┬─────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌─────▼─────┐ ┌──────▼──────┐ ┌─────▼─────┐
│ API │ │ Developer │ │ Semantic │
│ Gateway │ │ Portal │ │ Validator│
│ (Routing) │ │ (Sandbox) │ │ (SHACL) │
└─────┬─────┘ └─────────────┘ └───────────┘
│
│ Authenticated requests
│
┌─────────▼───────────────────────────────────────────────────────┐
│ API CONSUMERS │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Mobile App │ │ AI Agent │ │ 3rd-Party │ │
│ │ (Citizen) │ │ (Orchestr.) │ │ Service │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Flow:
1. Agencies publish OpenAPI specs to registry
2. Developers browse catalog, generate API clients
3. Consumers authenticate (OAuth), call APIs via gateway
4. Gateway enforces rate limits, logs usage
5. Analytics track API health (uptime, latency, errors)
API Standards & Specifications
OpenAPI 3.1 (Swagger)
All APIs must provide an OpenAPI specification—a machine-readable description of endpoints, parameters,
authentication, and data schemas. This enables automatic client generation and validation.
# Example: Tax Office API (vero.fi/api/openapi.yaml)
openapi: 3.1.0
info:
title: Finnish Tax Office API
version: 1.0.0
description: Access tax records, file returns, retrieve tax cards
contact:
name: Tax Office API Team
email: api@vero.fi
servers:
- url: https://api.vero.fi/v1
security:
- oauth2:
- tax.read
- tax.write
paths:
/taxpayers/{hetu}/tax-card:
get:
summary: Retrieve tax card for a taxpayer
operationId: getTaxCard
parameters:
- name: hetu
in: path
required: true
schema:
type: string
pattern: '^\d{6}[-+A]\d{3}[0-9A-Z]$'
description: Finnish personal identity code
responses:
'200':
description: Tax card retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TaxCard'
example:
hetu: "010190-900C"
taxPercentage: 18.5
additionalPercentage: 0
validFrom: "2026-01-01"
validTo: "2026-12-31"
'404':
description: Taxpayer not found
'403':
description: Unauthorized (missing consent or scope)
components:
schemas:
TaxCard:
type: object
properties:
hetu:
type: string
description: Personal identity code
taxPercentage:
type: number
format: float
description: Main tax withholding percentage
additionalPercentage:
type: number
format: float
validFrom:
type: string
format: date
validTo:
type: string
format: date
required:
- hetu
- taxPercentage
- validFrom
- validTo
Semantic API Design
APIs are linked to national data models via JSON-LD contexts. This ensures interoperability: different
agencies use the same vocabulary for "address," "person," "company."
# API response with semantic annotations (JSON-LD)
{
"@context": "https://tietomallit.suomi.fi/contexts/person/v1",
"@type": "Person",
"id": "urn:person:010190-900C",
"name": {
"@type": "FullName",
"givenName": "Matti",
"familyName": "Meikäläinen"
},
"address": {
"@type": "PostalAddress",
"streetAddress": "Mannerheimintie 5",
"postalCode": "00100",
"addressLocality": "Helsinki",
"addressCountry": "FI"
}
}
# Benefit: AI agents can understand this structure without custom parsing
# Same vocabulary used by DVV, Kela, Tax Office → automatic interoperability
Authentication & Authorization
| Method |
Use Case |
Example |
| OAuth 2.0 (User Delegation) |
Citizen authorizes app to access their data |
Mobile app fetches user's tax card (with consent) |
| Client Credentials (M2M) |
System-to-system integration (no user) |
Payroll system queries tax office API automatically |
| API Keys |
Public data APIs (no sensitive data) |
Weather data, public transport schedules |
| DID Auth |
Verifiable credential holders authenticate |
Company proves registration certificate to access B2B API |
Key Service APIs
Citizen Services
| API |
Provider |
Capabilities |
| Tax Card API |
Vero (Tax Office) |
Fetch tax card, update prepayment, file corrections |
| Population Register API |
DVV |
Address lookup, family relations, birth/death registration |
| Benefits API |
Kela |
Check eligibility, apply for benefits, track status |
| Healthcare API |
Kanta (National Health Archive) |
Fetch prescriptions, lab results, patient records (consent-based) |
| Education Credentials API |
Universities, schools |
Fetch degrees, transcripts, certificates as VCs |
Business Services
| API |
Provider |
Capabilities |
| Company Register API |
PRH |
Register company, update details, fetch certificates |
| VAT Registration API |
Vero |
Register for VAT, file returns, check VAT number validity |
| Customs Declaration API |
Tulli (Customs) |
Submit declarations, check clearance status, pay duties |
| Permits & Licenses API |
Various regulators |
Apply for permits (construction, food handling, etc.) |
| Public Procurement API |
Hilma |
Search tenders, submit bids, track awards |
Example: Automated Tax Filing
Use Case: Freelancer files quarterly VAT return via accounting software.
Traditional: Log into Vero portal, manually enter revenue, expenses → submit form.
With API:
- Accounting software (e.g., Procountor) aggregates transactions
- Software calls
POST /vat/returns (Vero API) with structured data
- Vero API validates submission → returns confirmation ID
- User receives notification: "VAT return filed successfully"
- Zero manual data entry, automatic submission before deadline
Result: Compliance becomes automatic—software handles filing, alerts on issues.
API Governance & Quality
API Lifecycle Management
| Stage |
Activities |
Governance |
| Design |
Define endpoints, schemas, error codes |
API design review board approves spec |
| Development |
Implement backend, generate OpenAPI spec |
Automated schema validation (CI/CD pipeline) |
| Testing |
Unit tests, integration tests, contract tests |
100% test coverage for public APIs |
| Publication |
Register in API catalog, publish docs |
SLA commitment (uptime, latency, rate limits) |
| Versioning |
Deprecate old versions, migrate consumers |
12-month deprecation notice, backward compatibility |
| Monitoring |
Track usage, errors, performance |
Alert on SLA breaches, publish uptime reports |
API Design Principles
Mandatory Standards (Finland):
- REST: Resource-based URLs, HTTP verbs (GET, POST, PUT, DELETE)
- JSON: Default format (XML optional for legacy)
- Semantic alignment: Use tietomallit.suomi.fi vocabularies
- OAuth 2.0: Standard authentication (no custom auth)
- OpenAPI 3.x: Machine-readable spec required
- HTTPS only: TLS 1.3, no plain HTTP
- Rate limiting: Transparent limits (e.g., 100 req/min)
- Error codes: Standard HTTP status + semantic error messages
Developer Experience (DX)
# Good DX Example: Developer journey
1. Visit api.suomi.fi (national API catalog)
2. Browse services: "Population Register API"
3. Read OpenAPI spec → understand endpoints
4. Register app → receive OAuth client credentials
5. Try sandbox: curl -H "Authorization: Bearer {token}" \
https://api-sandbox.dvv.fi/v1/persons/010190-900C
6. Receive test data → validate integration
7. Move to production → same API, different base URL
8. Monitor usage dashboard → track quota, errors
Key: Zero friction, comprehensive docs, sandbox environment
Challenge: Legacy systems don't expose APIs natively. Solution: API facade pattern—build
a REST API gateway in front of SOAP/mainframe systems. Gradual modernization without replacing backends.
Deployment Roadmap
| Phase |
Timeframe |
Deliverables |
| Foundation |
2024-2025 |
API gateway deployed, first 10 APIs published (core services) |
| Expansion |
2026 |
50+ APIs, developer portal live, OAuth federation operational |
| Semantic Layer |
2027 |
All APIs linked to tietomallit.suomi.fi, JSON-LD adoption |
| Third-Party Ecosystem |
2027-2028 |
100+ third-party apps built on gov APIs (fintech, healthtech) |
| AI Integration |
2028+ |
AI agents discover and compose APIs autonomously (agentic layer) |