Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

...