50 OpenAPI kirjeldus
API teenused on publitseeritud x-teel Keskkonnaameti alamsüsteemi "kotkas-pistrik" all.
Liidestumiseks tasub hetkel kasutada TEST x-tee teenuseid: ee-test/GOV/70008658/kotkas-pistrik/xroadservice/
Important
Toodangu keskkonna teenused on plaanis publitseerida 2026.a. IV kvartalis.
API teenuste nn masinloetav kirjeldus on koostatud OpenAPI v3 kirjeldusena.
Teenusekirjeldust on võimalik kätte saada kolmel viisil, mis on kirjeldatud alljärgnevates peatükkides.
API masinloetava OpenAPI kirjelduse saab alla laadida x-tee kataloogist "Teenuse WSDL/OpenAPI" sektsioonist.
X-teel publitseeritud REST teenuste OpenAPI kirjeldusi on võimalik alla laadida ka oma turvaserveri kaudu kasutades x-tee metadata protokolli teenust getOpenAPI :
curl --location --globoff '{{consumerSecurityServerUrl}}/{{restProtocolVersion}}/{{xRoadInstance}}/{{serviceMemberClass}}/{{serviceMemberCode}}/{{serviceSubsystemCode}}/getOpenAPI?serviceCode={{serviceCode}}' \
--header 'X-Road-Client: {{xRoadInstance}}/{{clientMemberClass}}/{{clientMemberCode}}/{{clientSubsystemCode}}' \
--header 'X-Road-Id: {{randomUUID}}'curl --location 'https://example-consumer-security-server.ee/r1/ee-test/GOV/70008658/kotkas-pistrik/getOpenAPI?serviceCode=xroadservice' \
--header 'X-Road-Client: ee-test/GOV/70008658/pistrik-client'{
"openapi": "3.0.3",
"info": {
"title": "Pistrik API",
"version": "v1",
"description": "\n# Request authentication\n\nIn order to use API service you need to provide the following headers:\n* \"X-Road-Client\" header, identifying the entity that intiates the service call;\n * In case of service platform (identified by the use of \"X-Road-Represented-Party\" header), must contain the registry code of the actual end-user (platform client);\n* \"Authorization\" header using the bearer authenication scheme and the authenication token generated in the self-service portal.\n",
"contact": {
"name": "Keskkonnaagentuuri klienditugi",
"url": "https://example-consumer-security-server.ee",
"email": "pistrik@envir.ee"
}
},
"paths": {
"/api/v1/balance/record": {
"post": {
"operationId": "post~apiV1_api_balance.record_add",
"summary": "Add record",
"tags": [
"Balance"
],
"parameters": [
{
"name": "X-Road-Client",
"schema": {
"type": "string",
"example": "EE/COM/10827700/pistrik-client"
},
"description": " Specifies the member/subsystem that is used as a service client - an entity that initiates the service call.",
"required": true,
"in": "header"
},
{
"name": "X-Road-UserId",
"schema": {
"type": "string",
"example": "EE38108100253"
},
"description": " User whose action initiated the request. The user ID should be prefixed with two-letter ISO country code.",
"required": false,
"in": "header"
},
{
"name": "X-Road-Id",
"schema": {
"type": "string",
"example": "fa2e18a5-c2cb-4d09-b994-f57727f7c3fb"
},
"description": "Unique identifier for this message. It is RECOMMENDED to use universally unique identifiers. If X-Road-Id is not provided, it SHALL be generated by the consumer Security Server.",
"required": false,
"in": "header"
},
{
"name": "X-Road-Issue",
"schema": {
"type": "string",
"example": "PT12345678"
},
"description": "Identifies received application, issue or document that was the cause of the service request. This field may be used by the client information system to connect service requests (and responses) to working procedures.",
"required": false,
"in": "header"
},
{
"name": "X-Road-Represented-Party",
"schema": {
"type": "string",
"example": "12168928"
},
"description": "The purpose of this header is to allow sending of additional information to the X-Road service providers in case when service client represents third party while issuing a query.",
"required": false,
"in": "header"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid",
"example": "0196a0ea-cfa6-7e23-a429-c979d511706c"
}
}
},
"example": {
"uuid": "0196a0ea-cfa6-7e23-a429-c979d511706c"
}
}
},
"description": "Successful operation"
},
"422": {
"content": {
"*/*": {
"schema": {}
}
},
"description": "Validation error"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BalanceRecordPostItem"
}
}
}
}
}
},
...
"securitySchemes": {
"token": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "string"
}
}
}
}Important
Soovitame OpenAPI kirjeldus alla laadida x-tee kataloogist või turvaserverist, kuna siis lisatakse kirjeldusse x-tee spetsiifilised päised (nt X-Road-Client, X-Road-Id jne). PISTRIKu iseteeninduskeskkonnas saab küll OpenAPI kirjelduse samuti alla laadida, kuid sellisel juhul puuduvad kirjelduses x-tee päised.
PISTRIKu iseteeninduskeskkonnast saab nii autentimata kui autenditud kasutaja teenusekirjeldust:
- Vaadata stiliseeritud Swaggerina aadressil: https://pistrikkoolitus.envir.ee/docs/swagger
- Alla laadida failina OpenAPI kirjeldusena aadressil: https://pistrikkoolitus.envir.ee/docs/openapi.json
PISTRIKu iseteeninduskeskonda sisseloginud kasutaja, kes omab äriregistri juriidilise isiku esindusõigust või PISTRIKu süsteemisisest volitust API ligipääsu haldus privileegiga saab Swaggeri ja OpenAPI kirjeldusele ligi menüüpunkti API kaudu:
