Eduterm:Interface: verschil tussen versies

Uit Kennisnet Developers Documentatie
Naar navigatie springen Naar zoeken springen
(0.7 eol)
(update to https)
 
(23 tussenliggende versies door 3 gebruikers niet weergegeven)
Regel 1: Regel 1:
  +
De interface beschrijving is opgedeeld in 3 delen:
−
De API is te bevragen via de url.
 
   
−
== Endpoints ==
 +
== Algemeen ==
  +
=== Endpoints ===
−
We adviseren om de 0.8 te gebruiken.
  
−
* <nowiki>http://api-beta.obk.kennisnet.nl/0.7/Query/</nowiki> = End of Life
 +
* <nowiki>https://api.onderwijsbegrippen.kennisnet.nl/1.0/Query</nowiki>
−
* <nowiki>http://api-beta.obk.kennisnet.nl/0.8/Query/</nowiki>
 +
* <nowiki>https://api.onderwijsbegrippen.kennisnet.nl/1.0/ListQueries</nowiki>
   
−
== Argumenten ==
 +
=== Argumenten ===
  +
Beide endpoints ondersteunen de volgende argumenten. Specifiek ondersteunde argumenten staan genoemd bij de individuele endpoint.
−
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.
  
   
 
{| class="wikitable"
  
{| class="wikitable"
Regel 24: Regel 24:
 
| 0-1
  
| 0-1
 
| string
  
| string
−
| Het uitvoerformaat, json, xml, html of csv. Standaard json.
 +
| Het uitvoerformaat, json, of html. Standaard json, via moderne browsers standaard html. Afhankelijk van de endpoint wat meer opties.
  +
|-
  +
|}
  +
  +
=== Foutmeldingen ===
  +
De 1.0 versie geeft HTTP errors terug, en het bericht in HTML.
  +
{| class="wikitable"
  +
|-
  +
! 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
  +
|-
  +
| 500 Internal Server Error
  +
| fout aan de Eduterm zijde, zie foutmelding voor meer info
  +
|}
  +
  +
== ListQueries ==
  +
Met het speciale ListQueries endpoint, kunnen de voor de API-key toegankelijke queries worden bekeken. In de HTML weergave wordt de "query run" link alleen getoond als alle parameters voorzien zijn van voorbeeldwaarden.
  +
  +
=== Endpoint ===
  +
* <nowiki>https://api.onderwijsbegrippen.kennisnet.nl/1.0/ListQueries</nowiki>
  +
  +
=== 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.
  +
{| class="wikitable"
  +
|-
  +
! HTTP Accept Header
  +
! format waarde
  +
! omschrijving
  +
|-
  +
| application/json
  +
| json
  +
|
  +
|-
  +
| text/html
  +
| html
  +
| formatted table
  +
|-
  +
|}
  +
  +
=== Voorbeeld Verzoek ===
  +
Deze query volgt de bovenstaande format interface voor html en json.
  +
<nowiki>https://api.onderwijsbegrippen.kennisnet.nl/1.0/ListQueries?api_key=geheim&format=json</nowiki>
  +
  +
=== Voorbeeld Respons (json) ===
  +
<syntaxhighlight lang="javascript">
  +
[
  +
{
  +
"default_endpoint": "OBKProductie",
  +
"allowed_endpoints": [
  +
"Kennisnetset201501",
  +
"OBKProductie",
  +
],
  +
"example_values": {
  +
"onderwijsniveau": "bk:512e4729-03a4-43a2-95ba-758071d1b725"
  +
},
  +
"parameters": [
  +
"onderwijsniveau"
  +
],
  +
"name": "VakLeergebieden"
  +
}
  +
]
  +
</syntaxhighlight>
  +
  +
== Query ==
  +
=== Endpoint ===
  +
* <nowiki>https://api.onderwijsbegrippen.kennisnet.nl/1.0/Query</nowiki>
  +
  +
=== Argumenten ===
  +
Naast de standaard argumenten, bestaat er voor Query een specifiek "endpoint" argument (die in de meeste gevallen niet wordt gebruikt).
  +
  +
{| class="wikitable"
  +
|-
  +
! naam
  +
! #
  +
! type
  +
! omschrijving
 
|-
  
|-
 
| endpoint
  
| endpoint
 
| 0-1
  
| 0-1
 
| string
  
| string
−
| Verwijst naar een optioneel RDF store endpoint, bijvoorbeeld Kennisnet-set. Default is het endpoint OBK.
 +
| Verwijst naar een optionele andere RDF store.
  +
|-
  +
|}
  +
  +
=== Datatype ===
  +
Waar de daadwerkelijke "values" in de JSON altijd als string terugkomen, kan er een datatype in de response gedefinieerd zijn:
  +
<syntaxhighlight lang="javascript">
  +
{
  +
"hasChildren": {
  +
"datatype": "http://www.w3.org/2001/XMLSchema#boolean",
  +
"type": "literal",
  +
"value": "true"
  +
}
  +
}
  +
</syntaxhighlight>
  +
In het bovenstaande voorbeeld kan de string "true" geinterpreteerd worden als een boolean TRUE. Een overzicht van de bekende datatypes:
  +
* <nowiki>http://www.w3.org/2001/XMLSchema#boolean</nowiki>
  +
* <nowiki>http://www.w3.org/2001/XMLSchema#integer</nowiki>
  +
  +
=== 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.
  +
{| class="wikitable"
  +
|-
  +
! HTTP Accept Header
  +
! format waarde
  +
! omschrijving
  +
|-
  +
| application/json
  +
| json
  +
| [https://www.w3.org/TR/sparql11-results-json/ sparql json]
  +
|-
  +
| text/html
  +
| html
  +
| formatted table
  +
|-
  +
| application/sparql-results+xml
  +
| xml
  +
| [https://www.w3.org/TR/rdf-sparql-XMLres/ sparql xml]
 
|-
  
|-
  +
|
  +
| csv
  +
| csv table
 
|}
  
|}
   
−
== Voorbeeld Verzoek ==
 +
=== Voorbeeld Verzoek ===
  +
{{ObkapiQuery|query=Onderwijsniveaus}}
−
<nowiki>http://api-beta.obk.kennisnet.nl/0.7/Query/Onderwijsniveaus?api_key=1b1dbdd8-aed6-4740-97f5-3116e34a351b</nowiki>
  
   
−
== Voorbeeld Respons ==
 +
=== Voorbeeld Respons (sparql json) ===
 
<syntaxhighlight lang="javascript">
  
<syntaxhighlight lang="javascript">
 
{
  
{
Regel 84: Regel 205:
 
</syntaxhighlight>
  
</syntaxhighlight>
   
−
== Foutmeldingen ==
  
−
De OBK-API geeft of een error json terug (zie voorbeeld), of een HTTP status code (bijvoorbeeld 401 voor een niet-geauthentiseerde api key en alleen headers opvragen geeft altijd een 405).
  
   
−
=== Voorbeeld ===
  
−
<syntaxhighlight lang="javascript">
  
−
{
  
−
"Message": "An error has occurred.",
  
−
"ExceptionMessage": "Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).",
  
−
"ExceptionType": "System.FormatException",
  
−
"StackTrace": " at System.Web.Http.ApiController.<InvokeActionWithExceptionFilters>d__1.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)\r\n at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n at System.Web.Http.Dispatcher.HttpControllerDispatcher.<SendAsync>d__0.MoveNext()"
  
−
}
  
−
</syntaxhighlight>
  
   
−
[[Categorie:OBK-API]]
 +
[[Categorie:Eduterm]]
 
[[Categorie:Interface]]
  
[[Categorie:Interface]]

Huidige versie van 6 mei 2020 om 07:53

De interface beschrijving is opgedeeld in 3 delen:

Algemeen

Endpoints

  • https://api.onderwijsbegrippen.kennisnet.nl/1.0/Query
  • https://api.onderwijsbegrippen.kennisnet.nl/1.0/ListQueries

Argumenten

Beide endpoints ondersteunen de volgende argumenten. Specifiek ondersteunde argumenten staan genoemd bij de individuele endpoint.

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, of html. Standaard json, via moderne browsers standaard html. Afhankelijk van de endpoint wat meer opties.

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
500 Internal Server Error fout aan de Eduterm zijde, zie foutmelding voor meer info

ListQueries

Met het speciale ListQueries endpoint, kunnen de voor de API-key toegankelijke queries worden bekeken. In de HTML weergave wordt de "query run" link alleen getoond als alle parameters voorzien zijn van voorbeeldwaarden.

Endpoint

  • https://api.onderwijsbegrippen.kennisnet.nl/1.0/ListQueries

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
text/html html formatted table

Voorbeeld Verzoek

Deze query volgt de bovenstaande format interface voor html en json. 

https://api.onderwijsbegrippen.kennisnet.nl/1.0/ListQueries?api_key=geheim&format=json

Voorbeeld Respons (json)

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

Query

Endpoint

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

Argumenten

Naast de standaard argumenten, bestaat er voor Query een specifiek "endpoint" argument (die in de meeste gevallen niet wordt gebruikt).

naam # type omschrijving
endpoint 0-1 string Verwijst naar een optionele andere RDF store.

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 sparql json
text/html html formatted table
application/sparql-results+xml xml sparql xml
csv csv table

Voorbeeld Verzoek

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

Voorbeeld Respons (sparql json)

{
    "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"
                }
            }
      ]}
}
Overgenomen van "https://developers.wiki.kennisnet.nl/index.php?title=Eduterm:Interface&oldid=10679"