Eduterm:Interface

De API is te bevragen via de url.

Endpoints

• http://api.onderwijsbegrippen.kennisnet.nl/1.0/Query/

Argumenten

Afhankelijk van het type zoekopdracht zijn er verschillende argument. Meer informatie vindt u op de OBK-API overzichtspagina voor uw api-key. Hieronder een overzicht van de generieke argumenten.

naam	#	type	omschrijving
api_key	1	uuid	De gebruikssleutel voor uw applicatie. Deze sleutel bepaalt tot welke zoekopdrachten toegang is verleend.
format	0-1	string	Het uitvoerformaat, json, xml, html of csv. Standaard json, via moderne browsers standaard html. Lees meer.
endpoint	0-1	string	Verwijst naar een optioneel RDF store endpoint, Kennisnetset2015.01 of OBKProductie. Default is het endpoint OBKProductie.

Voorbeeld Verzoek

https://api.onderwijsbegrippen.kennisnet.nl/1.0/Query/Onderwijsniveaus?api_key=geheim

Voorbeeld Respons

{
    "head": {
        "vars": [
            "onderwijsniveau",
            "onderwijsniveauLabel",
            "lomPurpose",
            "parent",
            "parentLabel"
        ]
    },
    "results": {
        "bindings": [
            {
                "onderwijsniveauLabel": {
                    "xml:lang": "nl",
                    "type": "literal",
                    "value": "Beroepsonderwijs en Volwasseneneducatie"
                },
                "onderwijsniveau": {
                    "type": "uri",
                    "value": "http://purl.edustandaard.nl/begrippenkader/caa97efc-a713-41ea-a845-1534ca65eac9"
                },
                "lomPurpose": {
                    "type": "literal",
                    "value": "educational level"
                }
            },
            {
                "onderwijsniveauLabel": {
                    "xml:lang": "nl",
                    "type": "literal",
                    "value": "HBO"
                },
                "onderwijsniveau": {
                    "type": "uri",
                    "value": "http://purl.edustandaard.nl/begrippenkader/be140797-803f-4b9e-81cc-5572c711e09c"
                },
                "lomPurpose": {
                    "type": "literal",
                    "value": "educational level"
                }
            }
      ]}
}

Datatype

Waar de daadwerkelijke "values" in de JSON altijd als string terugkomen, kan er een datatype in de response gedefinieerd zijn:

{
    "hasChildren": {
        "datatype": "http://www.w3.org/2001/XMLSchema#boolean",
        "type": "literal",
        "value": "true"
    }
}

In het bovenstaande voorbeeld kan de string "true" geinterpreteerd worden als een boolean TRUE. Een overzicht van de bekende datatypes:

• http://www.w3.org/2001/XMLSchema#boolean
• http://www.w3.org/2001/XMLSchema#integer

Formaat

Afhankelijk van de HTTP Accept Header of het meegegeven format, wordt het uitvoerformaat bepaald. Het format argument heeft bij het bepalen de voorkeur. Wanneer geen HTTP Accept Header of format argument worden gegeven, is json de default uitvoer.

HTTP Accept Header	format waarde	omschrijving
application/json	json	sparl json
text/html	html	formatted table
application/sparql-results+xml	xml	sparql xml
	csv	csv table

ListQueries

Met het speciale ListQueries endpoint, kunnen de voor de API-key toegankelijke queries worden bekeken. Deze query volgt de bovenstaande format interface voor html en json.

http://api.onderwijsbegrippen.kennisnet.nl/1.0/ListQueries?api_key=geheim

In de HTML weergave wordt de "query run" link alleen getoond als alle parameters voorzien zijn van voorbeeldwaarden.

JSON voorbeeld:

[
  {
    "default_endpoint": "OBKProductie",
    "allowed_endpoints": [
      "Kennisnetset201501",
      "OBKProductie",
    ],
    "example_values": {
      "onderwijsniveau": "bk:512e4729-03a4-43a2-95ba-758071d1b725"
    },
    "parameters": [
      "onderwijsniveau"
    ],
    "name": "VakLeergebieden"
  }
]

Foutmeldingen

De 1.0 versie geeft HTTP errors terug, en het bericht in HTML.

HTTP error	omschrijving
401 Unauthorized	request is goed, maar api-key niet geautoriseerd voor gevraagde query
400 Bad Request	fout in request, query of argumenten