{
"openapi": "3.0.0",
"info": {
"title": "Onderwijs Service Register API",
"version": "2.0.0"
},
"paths": {
"/api/v2/boards/{id}": {
"get": {
"tags": [
"Boards"
],
"summary": "Use this api endpoint to get a single board with an array of href links to it's schools.",
"operationId": "get_board",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique id of the board",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Returns a board by it's id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Board"
}
}
}
},
"404": {
"description": "Board with id {id} does not exist"
}
}
}
},
"/api/v2/endpoints/{id}": {
"get": {
"tags": [
"Endpoints"
],
"summary": "Use this api endpoint to get a single endpoint with href links to the school, the service\nand the service version it's linked to.",
"operationId": "get_endpoint",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique id of the endpoint",
"required": true,
"schema": {
"type": "integer",
"pattern": "\\d+"
}
}
],
"responses": {
"200": {
"description": "Returns an endpoint by it's id.
'_links.system' is optional.
When an API-Key is provided and matches the Systems-api key, the field 'user_is_owner' will return a boolean value (true/false). The default value is 'false'.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Endpoint"
}
}
}
},
"404": {
"description": "Endpoint with id {id} does not exist."
}
}
},
"put": {
"tags": [
"Endpoints"
],
"summary": "Use this api endpoint to update an endpoint by it's id.",
"operationId": "put_update_endpoint",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique id of the endpoint",
"required": true,
"schema": {
"type": "string",
"pattern": "\\d+"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateEndpointDTO"
}
}
}
},
"responses": {
"201": {
"description": "Endpoint is updated."
},
"400": {
"description": "Validation errors found."
},
"403": {
"description": "Not allowed, mandate expired or Endpoint has an inactivated system."
}
},
"security": [
{
"System": []
}
]
}
},
"/api/v2/endpoints": {
"get": {
"tags": [
"Endpoints"
],
"summary": "Use this api endpoint to get a list of endpoints with href links to the school, the service\nand service version they're linked to.",
"description": "One of the parameters `routing_id` or `school_oin` is required to perform a search on the endpoints.",
"operationId": "get_endpoint_list",
"parameters": [
{
"name": "routing_id",
"in": "query",
"description": "Routing id of the endpoint",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "school_oin",
"in": "query",
"description": "Oin of the school",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null,
"pattern": "(\\d|\\D){20}"
}
},
{
"name": "service_version_namespace",
"in": "query",
"description": "Namespace of the service version",
"required": true,
"allowEmptyValue": false,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "attributes",
"in": "query",
"description": "Attributes of the endpoint",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "reference_date",
"in": "query",
"description": "Reference date to check if an endpoint is/was active on a specific date",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "include_future_endpoints",
"in": "query",
"description": "Parameter to enable retrieving endpoints that are available in the future",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
}
],
"responses": {
"200": {
"description": "Returns a list of endpoints.
'_links.system' is optional.
When an API-Key is provided and matches the Systems-api key, the field 'user_is_owner' will return a boolean value (true/false). The default value is 'false'.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Endpoint"
}
}
}
}
},
"400": {
"description": "Validation error(s)"
}
}
},
"post": {
"tags": [
"Endpoints"
],
"summary": "Use this api endpoint to create a single endpoint.",
"description": "You need a mandate token in order to create one.",
"operationId": "post_create_endpoint",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEndpointDTO"
}
}
}
},
"responses": {
"201": {
"description": "Endpoint is created"
},
"400": {
"description": "### One of the following validation errors occurred:\n * Endpoint already exists. Combination of routing id and service version is already created.\n * The given service version does not allow endpoint registrations."
},
"403": {
"description": "Not allowed, mandate expired."
}
},
"security": [
{
"System": []
}
]
}
},
"/api/v2/endpoints/available_routing_id": {
"get": {
"tags": [
"Endpoints"
],
"summary": "This endpoint can be used to easily retrieve an available routing id given the context of a school (using the OIN) and a service version namespace.",
"description": "The parameter `routing_id` is optional.\n\n- when not provided, the current maximum routing id in use + 1 is returned;\n- when provided, the given routing_id is used as an offset from which the next available routing id will be returned.",
"operationId": "get_endpoint_available_routing_id",
"parameters": [
{
"name": "routing_id",
"in": "query",
"description": "Routing id",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "school_oin",
"in": "query",
"description": "Oin of the school",
"required": true,
"allowEmptyValue": false,
"schema": {
"type": "string",
"default": null,
"pattern": "(\\d|\\D){20}"
}
},
{
"name": "service_version_namespace",
"in": "query",
"description": "Namespace of the service version",
"required": true,
"allowEmptyValue": false,
"schema": {
"type": "string",
"default": null
}
}
],
"responses": {
"200": {
"description": "Returns an available routing_id.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"routing_id": {
"type": "string"
}
},
"type": "object"
}
}
}
}
},
"400": {
"description": "Validation error(s)"
}
}
}
},
"/api/v2/mandates/{id}": {
"get": {
"tags": [
"Mandates"
],
"summary": "Use this api endpoint to get a single mandate with href links to the school and service it's linked to.",
"description": "You can only use this api endpoint when you are a system and the mandate requested belongs to\nyour organisation.",
"operationId": "get_mandate",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique id of the mandate",
"required": true,
"schema": {
"type": "integer",
"pattern": "\\d+"
}
}
],
"responses": {
"200": {
"description": "Returns a mandate by it's id. '_links.system' is optional.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Mandate"
}
}
}
},
"403": {
"description": "You are not allowed to view this mandate"
},
"404": {
"description": "Mandate with id {id} does not exist"
}
}
}
},
"/api/v2/mandates": {
"get": {
"tags": [
"Mandates"
],
"summary": "Use this api endpoint to find out if a school has mandated a certain system\n(and thereby the suppliers of that system) for a service version.",
"description": "When n System api-key is provided in the header you will query this endpoint as\nA system. Then when the requested mandate(s) exist you will be provided with the corresponding\nmandates.\n\nWhen the Mandates do not belong to the System that is querying then you will get an empty\nbody response 204\n\nIt is mandatory to provide either a service_version namespace OR a service_code\n\nReference date can be used to check if a mandate exists/existed on a certain date.",
"operationId": "get_mandate_list",
"parameters": [
{
"name": "supplier_oin",
"in": "query",
"description": "Oin of the supplier",
"required": true,
"allowEmptyValue": false,
"schema": {
"type": "string",
"default": null,
"pattern": "(\\d|\\D){20}"
}
},
{
"name": "school_oin",
"in": "query",
"description": "Oin of the school",
"required": true,
"allowEmptyValue": false,
"schema": {
"type": "string",
"default": null,
"pattern": "(\\d|\\D){20}"
}
},
{
"name": "service_version_namespace",
"in": "query",
"description": "Namespace of the service version. If empty, a service_code is required.",
"required": false,
"allowEmptyValue": false,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "reference_date",
"in": "query",
"description": "Reference date for getting mandate on a specific date",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "service_code",
"in": "query",
"description": "Service code. If empty, a service_version_namespace is required.",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
}
],
"responses": {
"200": {
"description": "Mandate for system exists and is valid. '_links.system' is optional.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Mandate"
}
}
}
},
"204": {
"description": "Mandate for system exists and is valid"
},
"400": {
"description": "There is a problem with the system query parameters"
},
"404": {
"description": "Mandate not found"
}
}
}
},
"/api/v2/schools/{id}": {
"get": {
"tags": [
"Schools"
],
"summary": "Use this api endpoint to get a single school with an href link to it's board.",
"operationId": "get_school",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique id of the school",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Returns a school by it's id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/School"
}
}
}
},
"404": {
"description": "School with id {id} does not exist"
}
}
}
},
"/api/v2/schools": {
"get": {
"tags": [
"Schools"
],
"summary": "Use this api endpoint to get a list of multiple schools.",
"operationId": "get_school_list",
"parameters": [
{
"name": "brin",
"in": "query",
"description": "Brin of the school",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "oin",
"in": "query",
"description": "Oin of the school",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "oa_id",
"in": "query",
"description": "Onderwijs aanbieder id of the school",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
},
{
"name": "name",
"in": "query",
"description": "Name of the school",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
}
],
"responses": {
"200": {
"description": "Returns a list of schools",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/School"
}
}
}
}
}
}
}
},
"/api/v2/school-mandates": {
"get": {
"tags": [
"Schools mandates for service"
],
"summary": "Returns a list with schools that have a mandate for a specific service supplied by you.",
"operationId": "get_school_overview_with_mandates_for_service_for_system",
"parameters": [
{
"name": "service_code",
"in": "query",
"description": "Code of service that you want to get schools with mandates from",
"required": true,
"allowEmptyValue": false,
"schema": {
"type": "string",
"default": null
}
}
],
"responses": {
"200": {
"description": "Returns a list of schools",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SchoolMandateSystemServiceDTO"
}
}
}
}
},
"401": {
"description": "Authorization required"
}
}
}
},
"/api/v2/services/{id}": {
"get": {
"tags": [
"Services"
],
"summary": "Use this api endpoint to get a single service.",
"operationId": "get_service",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique id of the service",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Returns a service by it's id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Service"
}
}
}
},
"400": {
"description": "Validation error(s)"
},
"404": {
"description": "Service with id {id} does not exist"
}
}
}
},
"/api/v2/services": {
"get": {
"tags": [
"Services"
],
"summary": "Use this api endpoint to get a list of services.",
"operationId": "get_services",
"parameters": [
{
"name": "name",
"in": "query",
"description": "(Part of) service name",
"required": false,
"allowEmptyValue": true,
"schema": {
"type": "string",
"default": null
}
}
],
"responses": {
"200": {
"description": "Returns all services (possibly filtered by name) ",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Service2"
}
}
}
}
}
}
}
},
"/api/v2/systems/{uuid}": {
"get": {
"tags": [
"Systems"
],
"summary": "Use this api endpoint to get a single active system.",
"operationId": "get_system",
"parameters": [
{
"name": "uuid",
"in": "path",
"description": "Unique UUID of the system",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Returns an active system by it's UUID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/System"
}
}
}
},
"400": {
"description": "Validation error(s)"
},
"404": {
"description": "System with UUID {uuid} does not exist"
}
}
}
},
"/api/v2/systems": {
"get": {
"tags": [
"Systems"
],
"summary": "Use this api endpoint to get all active systems.",
"operationId": "get_systems",
"responses": {
"200": {
"description": "Returns all active systems",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/System2"
}
}
}
}
}
}
}
},
"/api/v2/service-versions/{id}": {
"get": {
"tags": [
"Service versions"
],
"summary": "Use this api endpoint to get a single service version with an href link to it's service.",
"operationId": "get_service-version",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Unique id of the service version",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Returns a service version by it's id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServiceVersion"
}
}
}
},
"400": {
"description": "Validation error(s)"
},
"404": {
"description": "Service version with id {id} does not exist"
}
}
}
},
"/api/v2/service-versions": {
"get": {
"tags": [
"Service versions"
],
"summary": "Use this api endpoint to get a list of service versions for a service.",
"operationId": "get_service-versions",
"parameters": [
{
"name": "code",
"in": "query",
"description": "Service code",
"required": true,
"allowEmptyValue": false,
"schema": {
"type": "string",
"default": null
}
}
],
"responses": {
"200": {
"description": "Returns a list of active service versions for a given service.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceVersion"
}
}
}
}
},
"400": {
"description": "Validation error(s)"
},
"404": {
"description": "Service with code {code} does not exist"
}
}
}
},
"/api/v2/service-versions/copy-endpoints-from-service-version": {
"post": {
"tags": [
"Copy endpoints to service versions"
],
"summary": "Use this api endpoint to copy endpoints from another service version.",
"description": "The service version to copy to can not have active endpoints for the calling system.",
"operationId": "post_service-version-copy-endpoints",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CopyEndpointsDTO"
}
}
}
},
"responses": {
"200": {
"description": "Returns the updated service version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServiceVersion"
}
}
}
},
"400": {
"description": "Validation error(s)"
},
"404": {
"description": "Service version with namespace {namespace} does not exist"
}
},
"security": [
{
"System": []
}
]
}
}
},
"components": {
"schemas": {
"Board": {
"properties": {
"number": {
"type": "string"
},
"name": {
"type": "string"
},
"board_id": {
"type": "string"
}
},
"type": "object"
},
"Endpoint": {
"properties": {
"attributes": {
"type": "string"
},
"routing_id": {
"type": "string"
},
"url": {
"type": "string"
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-11-19"
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2022-11-19"
},
"user_is_owner": {
"type": "boolean",
"default": false
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"school": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"service": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"service-version": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"system": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"UpdateEndpointDTO": {
"required": [
"routing_id",
"url",
"service_version_namespace"
],
"properties": {
"routing_id": {
"type": "string",
"pattern": "0000000700{2}[0-9]{2}[A-Z]{2}00\\d{3}"
},
"url": {
"type": "string",
"maxLength": 4096
},
"service_version_namespace": {
"type": "string"
},
"attributes": {
"type": "string"
},
"start_date": {
"type": "string"
},
"end_date": {
"type": "string"
},
"id": {
"type": "integer"
}
},
"type": "object"
},
"CreateEndpointDTO": {
"required": [
"routing_id",
"url",
"service_version_namespace",
"mandate_token"
],
"properties": {
"routing_id": {
"type": "string",
"pattern": "0000000700{2}[0-9]{2}[A-Z]{2}00\\d{3}"
},
"url": {
"type": "string",
"maxLength": 4096
},
"service_version_namespace": {
"type": "string"
},
"attributes": {
"type": "string"
},
"start_date": {
"type": "string",
"default": null,
"nullable": true
},
"end_date": {
"type": "string"
},
"mandate_token": {
"type": "string"
}
},
"type": "object"
},
"Mandate": {
"properties": {
"token": {
"type": "string"
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-11-19"
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2022-11-19"
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"school": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"service": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"system": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"School": {
"properties": {
"name": {
"type": "string"
},
"oin": {
"type": "string"
},
"brin": {
"type": "string"
},
"oa_id": {
"type": "string"
},
"sectors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Sector"
}
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"board": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"SchoolMandateSystemServiceDTO": {
"properties": {
"school_brin": {
"type": "string"
},
"school_oin": {
"type": "string"
},
"school_oa_id": {
"type": "string"
},
"school_name": {
"type": "string"
},
"mandates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Mandate2"
},
"default": []
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"Service": {
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"Service2": {
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"System": {
"properties": {
"uuid": {
"type": "string"
},
"name": {
"type": "string"
},
"inactivated_at": {
"type": "string",
"format": "date-time"
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"System2": {
"properties": {
"uuid": {
"type": "string"
},
"name": {
"type": "string"
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"ServiceVersion": {
"properties": {
"namespace": {
"type": "string"
},
"status": {
"type": "string",
"default": "active"
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
},
"service": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
},
"CopyEndpointsDTO": {
"required": [
"service_version_namespace_to_copy_to",
"service_version_namespace_to_copy_from"
],
"properties": {
"service_version_namespace_to_copy_to": {
"type": "string"
},
"service_version_namespace_to_copy_from": {
"type": "string"
}
},
"type": "object"
},
"Sector": {
"properties": {
"code": {
"type": "string"
}
},
"type": "object"
},
"Mandate2": {
"properties": {
"token": {
"type": "string"
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-11-19"
},
"end_date": {
"type": "string",
"format": "date-time",
"example": "2022-11-19"
},
"_links": {
"properties": {
"self": {
"properties": {
"href": {
"type": "string"
}
},
"type": "object"
}
},
"readOnly": true
}
},
"type": "object"
}
}
},
"tags": [
{
"name": "Boards"
},
{
"name": "Endpoints"
},
{
"name": "Mandates"
},
{
"name": "Schools"
},
{
"name": "Schools mandates for service"
},
{
"name": "Services"
},
{
"name": "Systems"
},
{
"name": "Service versions"
},
{
"name": "Copy endpoints to service versions"
}
]
}