Skip to main content
Developers Repository

Versioning & Lifecycle

This document serves as a guide for the Versioning & Lifecycle govgr, part of the technical documentation for developers working within the gov.gr ecosystem. It outlines how API versions are managed in gov.gr projects and what developers need to know about active, deprecated, and testing APIs.

Types of Versions​

  • v1: First version of an API. Typically includes the minimum required fields/functions.
  • v2+: Newer versions, with backward-incompatible changes or improvements.
  • test/vX: Versions intended exclusively for sandbox environments.
  • deprecated: A version marked for deprecation (mentioned for reference but should no longer be used).

URL Naming Conventions​

APIs should follow a clear pattern:

  • RESTful API: https://api.gov.gr/v1/service-name/...
  • SOAP Endpoint: https://test.gsis.gr/esbpilot/<service> (with versioning in the WSDL)

Note: Do not change the version in the same endpoint without proper reference.

Deprecation Policy​

  • Every deprecated API must be clearly marked as such in the relevant documentation.
  • Deprecation must be announced at least 3 months in advance.
  • An alternative should be provided (e.g., v2 endpoint).

Developer Responsibilities​

  • Monitor change announcements (changelogs or emails).
  • Never rely on undocumented behavior.
  • If you are using an old version (e.g., v1), plan the migration in a timely manner.

Useful Examples​

  • v1: https://api.gov.gr/v1/citizen-profile
  • v2: https://api.gov.gr/v2/citizen-profile
  • deprecated: https://api.gov.gr/v1/deprecated-service
  • test: https://test.gsis.gr/esbpilot/individualConfirmationService
  • Use headers (e.g., Accept: application/vnd.govgr.v2+json) if the API supports it.
  • Keep logs of the version you are using for debugging/compatibility.
  • If an API has no versioning, request clarification from the technical team.
We'd love your feedback
Was this helpful?