Webservices en API¶
Op deze pagina zijn het ontwerp en implementatie van de application programming interface (API) en het bijbehorende gegevensstructuren, protocollen, etc. van de OpenTaal webservices gedocumenteerd.
Aanpak¶
Incrementeel zal hier het ontwerp en implementatie worden besproken. Momenteel is de insteek klein te beginnen maar wel vooruit te blijven denken om met maximale herbruikbaarheid nieuwe webservices te ontwikkelen. In verband met internationaal gebruik zullen de namen in de API zo veel mogelijk in het Engels zijn. Alles met ??? verdient correct ingevuld te worden.
Vraag, moeten output variabelen altijd aanwezig zijn om bij afwezigheid NULL in de database te represteren t.o.v. een lege string in de database???
Gebruik van JSON en REST???
Security¶
De webservices zullen zich moeten beschermen tegen misbruik.
API-sleutel¶
Iedereen (ook intern) die gebruik wil maken van de OpenTaal webservices dient zich te identificeren met een API-sleutel. Hiermee kunnen alleen geregistreede gebruikers de webserviceaanroepen en gebruikers die de voorwaarden niet respecteren (tijdelijk) worden geblokkeerd.
Het registratieproces zal niet geautomatiseerd zijn en zal gemiddels ? werkdagen duren voordat een partij een API-sleutel ontvangt. Deze API-sleutel is een uniek per gebruiker en werkt voor aanroepen vanaf een bepaalde fully qualified domain name die tijdens de registratieoprocedure is opgenomen. Wijzigen van de fully qualified domain name die bij een API-sleutel hoord duurt ? werkdagen waarna voor ??? werkdagen de oude fully qualified domain name ook nog zal werken.
Throtling¶
Per API key zal er aan throtling gedaan moeten worden om (bedoelde of onbedoelde) overbelasting van de server te voorkomen. De meest eenvoudige implementatie is om niet meer dan ??? API-aanroepen per API-sleutel per miliseconden toe te laten.
Data structure: versions¶
key-value dictionary:
| name | type | examples |
| key | char??? | 1_00, 1_10G, 2_00, 2_10, next_version |
| value | char | ??? |
Service: api.opentaal.org/word_details¶
Word details for a single word.
| I/O | required | type | name | default | comment |
| input | yes | char??? | api_key | ||
| input | no | char75 | word | 'woorddetails' | default can be used as test, may not contain regular expressions |
| output | no | key-value dictonary | versions | ||
| output | no | char??? | comments | ||
| output | no | char75 | alternative |
Moet deze eigenlijk niet generieker zijn net als de volgende en ook regex accepteren en meerdere woorddetails kunnen teruggeven??? Kunnen we er altijd nog kiezen om regex uit te schakelen en daardoor output tot maar een woord te beperken.
Service: api.opentaal.org/harvested_sentence¶
Harvested sentences containing a phrase.
| I/O | required | type | name | default | comment |
| input | yes | char??? | api_key | ||
| input | no | char75 | phrase | 'Stichting OpenTaal' | default can be used as test, may contain regular expressions |
| output | no | list of char??? | sentences |