Go directly to contents.
Best practices for developers
API design in public administration
  1. Guide's start page
  2. Before procurement
  3. During the development process
  4. When a program or application has been completed
    1. Publish the data model and source code openly
    2. Support software developers
    3. Create a high-quality deployment process
    4. Publish the life cycle and create versioning
      1. Ensure systematic versioning
      2. Different versioning styles
      3. Remember to communicate about versioning and life cycle
    5. Support experiments and use
    6. Plan retirement
  5. Glossary

Publish the life cycle and create versioning

Ensure systematic versioning

API versioning is a way of managing and updating functionalities. Versioning allows you to modify the API without breaking changes in applications that use it.

Versioning allows various users to use different versions without having to continually update their code as new changes are brought in.

Versioning allows you to:

  • offer new features
  • maintain backward compatibility
  • give developers time to migrate from older versions to newer ones.

Drawing up the data model carefully will reduce the need for versioning.

Updated: 5/5/2026

Different versioning styles

Different versioning styles have both advantages and disadvantages.

Versioning is often required when using RESTful architecture style. GraphQL APIs require less versioning and often use the first method of the Table below.

API versioning styles in RESTful architecture

Method

Practical examples

Description

Using URLs

https://esimerkki.fi/fi/v1/

https://esimerkki.fi/fi/v2/

Advantages: Using cache memory is easy.
Disadvantages: A version update may require major changes to client software.

Using query parameters

api/…/tuotteet?versio=1

api/…/tuotteet?versio=2

Advantages: Straightforward implementation.

Disadvantages: More difficult to use if there is a large number of parameters.

Using an HTTP header

curl -H “Accepts-version: 1.0”
http://www.example.com
/api/products

Advantages: Does not increase the length of the URL. Disadvantages: Uses tailored headers.

Versioning in connection with resource format request

curl -H “Accept: application/vnd.xm.device+json;
version=1”

curl -H “Accept: application/vnd.xm.device+json;
version=2”

Advantages: The URL does not change.

Disadvantages: More difficult to test and trial in a web browser.


The table presents different mechanisms for indicating the version. In addition, it is useful to consider what kinds of content-related changes should be versioned and how. Such as semantic versioning (Semantic Versioning 2.0.0 | Semantic VersioningOpens in a new window.) can help in answering this question.

Updated: 5/5/2026

Remember to communicate about versioning and life cycle

Effective API versioning is based on life cycle thinking, correctly chosen technological solutions and sufficient communication.

It is important to communicate about

  • release of a new version
  • modifications to a version
  • the period during which the old version will be supported.

Updated: 5/5/2026

Are you satisfied with the content on this page?

Glossary