...
OpenAPI-specificaties
| Swagger integration |
|---|
{
"openapi": "3.0.0",
"info": {
"title": "Certificates Endpoint",
"version": "1.0",
"description": "# Certificates API\n\nThis documentation contains the API description that is expected from a source of certificates that is supplying certificates to the Burgerprofiel platform of the Flemish Government."
},
"servers": [
{
"url": "https://burgerprofiel.vlaanderen.be/v1",
"description": "Burgerprofiel"
}
],
"paths": {
"/certificates/{ssn}": {
"get": {
"tags": [
"Certificates"
],
"summary": "Certificates List",
"parameters": [
{
"name": "ssn",
"in": "path",
"description": "Social security number",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/hal+json": {
"schema": {
"$ref": "#/components/schemas/List-Certificates"
},
"examples": {
"Full Example": {
"value": {
"certificates": [
{
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language": "nl",
"name": "Dienstencheques 2019",
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl/download"
}
]
},
{
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language": "en",
"name": "Dienstencheques 2019",
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/en"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/en/download"
}
]
},
{
"id": "8a4faf91-300e-46f0-8dad-0e1e572dbca1",
"language": "nl",
"name": "Sportkamp Tennis",
"community": 23088,
"year": 2018,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8a4faf91-300e-46f0-8dad-0e1e572dbca1"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8a4faf91-300e-46f0-8dad-0e1e572dbca1/download"
}
]
},
{
"id": "25da5b3c-4de4-457c-a803-cea5cafbfff5",
"language": "nl",
"name": "Dienstencheques 2018",
"year": 2018,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/25da5b3c-4de4-457c-a803-cea5cafbfff5"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/25da5b3c-4de4-457c-a803-cea5cafbfff5/download"
}
]
},
{
"id": "8e3405ea-ef23-4d8a-b5b4-9cb645ac312b",
"language": "nl",
"name": "Deelname opleiding recreatiemedewerker",
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8e3405ea-ef23-4d8a-b5b4-9cb645ac312b"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8e3405ea-ef23-4d8a-b5b4-9cb645ac312b/download"
}
]
},
{
"id": "8df1a0b0-1278-46a7-a3dc-cce7f593d02c",
"language": "nl",
"name": "Sportkamp tennis",
"community": 11002,
"year": 2012,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8df1a0b0-1278-46a7-a3dc-cce7f593d02c"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8df1a0b0-1278-46a7-a3dc-cce7f593d02c/download"
}
]
},
{
"id": "34492c86-7bf8-4d96-9e61-e3c2f51d172a",
"language": "nl",
"name": "Dienstencheques 2015",
"year": 2015,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/34492c86-7bf8-4d96-9e61-e3c2f51d172a"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/34492c86-7bf8-4d96-9e61-e3c2f51d172a/download"
}
]
},
{
"id": "a681c382-8e99-4757-9fdb-487b9b6aeb78",
"language": "nl",
"name": "Trainersopleiding voetbal",
"community": 71053,
"year": 2013,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/a681c382-8e99-4757-9fdb-487b9b6aeb78"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/a681c382-8e99-4757-9fdb-487b9b6aeb78/download"
}
]
},
{
"id": "6973ab14-15c6-4ee7-944c-9d1162d9de71",
"language": "nl",
"name": "Dienstencheques 2014",
"year": 2014,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/6973ab14-15c6-4ee7-944c-9d1162d9de71"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/6973ab14-15c6-4ee7-944c-9d1162d9de71/download"
}
]
},
{
"id": "d61fdf2e-8099-4757-93d9-2709f1ce1ae2",
"language": "nl",
"name": "Vlaamse kinderbijslag",
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/d61fdf2e-8099-4757-93d9-2709f1ce1ae2"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/d61fdf2e-8099-4757-93d9-2709f1ce1ae2/download"
}
]
}
],
"pageMetadata": {
"number": 1,
"size": 10,
"totalElements": 40,
"totalPages": 4
},
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0"
},
{
"rel": "next",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=1"
},
{
"rel": "start",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0"
},
{
"rel": "last",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=3"
}
]
}
},
"Last page, no more next page": {
"value": {
"certificates": [
{
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language": "nl",
"name": "Dienstencheques 2019",
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/download"
}
]
},
{
"id": "57faeea1-ff3b-4c65-989c-e2175610c2b0",
"language": "nl",
"name": "Sportkamp Volleybal",
"community": 21004,
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/57faeea1-ff3b-4c65-989c-e2175610c2b0"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/57faeea1-ff3b-4c65-989c-e2175610c2b0/download"
}
]
},
{
"id": "8a4faf91-300e-46f0-8dad-0e1e572dbca1",
"language": "nl",
"name": "Sportkamp Tennis",
"community": 23088,
"year": 2018,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8a4faf91-300e-46f0-8dad-0e1e572dbca1"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8a4faf91-300e-46f0-8dad-0e1e572dbca1/download"
}
]
}
],
"pageMetadata": {
"number": 3,
"size": 10,
"totalElements": 23,
"totalPages": 3
},
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=2"
},
{
"rel": "start",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0"
},
{
"rel": "last",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=2"
}
]
}
},
"First page is last page": {
"value": {
"certificates": [
{
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language": "nl",
"name": "Dienstencheques 2019",
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/download"
}
]
},
{
"id": "57faeea1-ff3b-4c65-989c-e2175610c2b0",
"language": "nl",
"name": "Sportkamp Volleybal",
"community": 21004,
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/57faeea1-ff3b-4c65-989c-e2175610c2b0"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/57faeea1-ff3b-4c65-989c-e2175610c2b0/download"
}
]
},
{
"id": "8a4faf91-300e-46f0-8dad-0e1e572dbca1",
"language": "nl",
"name": "Sportkamp Tennis",
"community": 23088,
"year": 2018,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8a4faf91-300e-46f0-8dad-0e1e572dbca1"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/8a4faf91-300e-46f0-8dad-0e1e572dbca1/download"
}
]
}
],
"pageMetadata": {
"number": 1,
"size": 10,
"totalElements": 3,
"totalPages": 1
},
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0"
},
{
"rel": "start",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0"
},
{
"rel": "last",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0"
}
]
}
}
}
}
}
},
"403": {
"description": "Access Denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
},
"examples": {
"Example": {
"value": {
"title": "An error occurred!",
"detail": "Access Denied",
"status": 403
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
},
"examples": {
"Example": {
"value": {
"title": "An error occurred!",
"detail": "Could not find the certificate you are looking for.",
"status": 404
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
},
"examples": {
"Example": {
"value": {
"title": "An error occurred!",
"detail": "<description of the internal server error>",
"status": 500
}
}
}
}
}
}
}
}
},
"/certificates/{ssn}/{certificateId}/{language}": {
"get": {
"tags": [
"Certificates"
],
"summary": "Certificate Details",
"description": "",
"parameters": [
{
"name": "ssn",
"in": "path",
"description": "Social security number",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string"
}
},
{
"name": "certificateId",
"in": "path",
"description": "ID of the certificate, defined as path parameter here (can be query parameter too)",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string"
}
},
{
"name": "language",
"in": "path",
"description": "Language of the certificate, defined as path parameter here (can be query parameter too)",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/hal+json": {
"schema": {
"$ref": "#/components/schemas/Item-Certificate"
},
"examples": {
"only-required": {
"value": {
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language": "nl",
"name": "certificate-1234",
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl/download"
}
]
}
},
"only-year": {
"value": {
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language": "nl",
"name": "certificate-1234",
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl/download"
}
]
}
},
"only-community": {
"value": {
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language": "nl",
"name": "certificate-1234",
"community": 21004,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl/download"
}
]
}
},
"full-certificate": {
"value": {
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language": "nl",
"name": "certificate-1234",
"community": 21004,
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl/download"
}
]
}
}
}
}
}
},
"403": {
"description": "Access Denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
},
"examples": {
"Example": {
"value": {
"title": "An error occurred!",
"detail": "Access Denied",
"status": 403
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
},
"examples": {
"Example": {
"value": {
"title": "An error occurred!",
"detail": "Could not find the certificate you are looking for.",
"status": 404
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
},
"examples": {
"Example": {
"value": {
"title": "An error occurred!",
"detail": "<description of the internal server error>",
"status": 500
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ProblemDetails": {
"title": "Problem details",
"required": [
"type",
"title",
"detail",
"status"
],
"type": "object",
"properties": {
"title": {
"type": "string"
},
"detail": {
"type": "string"
},
"status": {
"format": "int32",
"type": "integer"
}
},
"example": {
"title": "Er heeft zich een fout voorgedaan!",
"detail": "",
"status": 400
}
},
"Item-Certificate": {
"title": "Certificate",
"required": [
"id",
"links",
"name"
],
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"year": {
"type": "integer"
},
"community": {
"type": "integer"
},
"links": {
"$ref": "#/components/schemas/Common-Item-Links"
}
}
},
"Common-General-Link": {
"title": "Link",
"required": [
"href",
"rel"
],
"type": "object",
"properties": {
"rel": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"Common-Item-Links": {
"title": "Links For Item",
"type": "array",
"items": {
"$ref": "#/components/schemas/Common-General-Link"
}
},
"Common-List-Links": {
"title": "Links For List",
"type": "array",
"items": {
"$ref": "#/components/schemas/Common-General-Link"
}
},
"Common-List-PageMetadata": {
"title": "PageMetadata",
"required": [
"number",
"size",
"totalElements",
"totalPages"
],
"type": "object",
"properties": {
"size": {
"type": "integer"
},
"totalElements": {
"type": "integer"
},
"totalPages": {
"type": "number"
},
"number": {
"type": "number"
}
}
},
"List-Certificates": {
"required": [
"certificates",
"links",
"pageMetaData"
],
"type": "object",
"properties": {
"certificates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Item-Certificate"
}
},
"links": {
"$ref": "#/components/schemas/Common-List-Links"
},
"pageMetaData": {
"$ref": "#/components/schemas/Common-List-PageMetadata"
}
}
}
}
}
} |
JSON
We gebruiken application/hal+json als standaard. Deze specifieke JSON geeft aan dat de payload voldoet aan de HATEOAS-standaard.
...
Een URL voor uw endpoint kan er als volgt uitzien: https://<hostname>/v1/certificates/<ssn><insz>?limit=10&page=0
Verplichte velden
...
De parameters voor de paginering en de maximumwaarden maken deel uit van de URL: https://<hostname>/v1/certificates/<ssn><insz>?limit=10&page=0. T
De API-client kan de parameter met de grenswaarde bepalen. Als de client 10 items vraagt, dan moeten er 10 worden gegeven. Vraagt de client er 50, dan moeten er 50 worden gegeven.
...
https://<hostname>/v1/certificates/<ssn><insz>?limit=10&page=0https://<hostname>/v1/certificates/<ssn><insz>?limit=10https://<hostname>/v1/certificates/<ssn><insz>?page=0
Worden er geen defaultwaarden gedefinieerd, gebruik dan deze logische defaultwaarden:
...