@itslanguage/api

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Home - ITSLanguage JavaScript SDK</title> <meta name="description" content="Speech technology for language education. JSDoc 3 website for the JavaScript SDK." /> <meta name="keywords" content="itslangauge, jsdoc, documentation, speech, speech technology" /> <meta name="keyword" content="itslangauge, jsdoc, documentation, speech, speech technology" /> <meta property="og:title" content="ITSLanguage JavaScript SDK"/> <meta property="og:type" content="website"/> <meta property="og:image" content="https://avatars0.githubusercontent.com/u/20972344?s=400&u=73936e7fa2d2a1e5c180a11675bf9166d3717a6d&v=4"/> <meta property="og:site_name" content="ITSLanguage JavaScript SDK"/> <meta property="og:url" content="http://itslanguage.github.io/itslanguage-js/"/> <script src="scripts/prettify/prettify.js"></script> <script src="scripts/prettify/lang-css.js"></script>  <link type="text/css" rel="stylesheet" href="styles/prettify.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc.css"> <script src="scripts/nav.js" defer></script> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger" /> <label for="nav-trigger" class="navicon-button x"> <div class="navicon"></div> </label> <label for="nav-trigger" class="overlay"></label> <nav > <input type="text" id="nav-search" placeholder="Search" /> <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/itslanguage/itslanguage-js" target="_blank" class="menu-item" id="repository" >Github repo</a></h2><h3>Modules</h3><ul><li><a href="module-api.html">api</a><ul class='members'><li data-type='member'><a href="module-api.html#.version">version</a></li></ul><ul class='methods'><li data-type='method'><a href="module-api.html#.createItslApi">createItslApi</a></li></ul></li><li><a href="module-api_authentication.html">api/authentication</a><ul class='methods'><li data-type='method'><a href="module-api_authentication.html#.assembleScope">assembleScope</a></li><li data-type='method'><a href="module-api_authentication.html#.authenticate">authenticate</a></li><li data-type='method'><a href="module-api_authentication.html#.impersonate">impersonate</a></li></ul></li><li><a href="module-api_basicauth.html">api/basicauth</a><ul class='methods'><li data-type='method'><a href="module-api_basicauth.html#.create">create</a></li></ul></li><li><a href="module-api_broadcaster.html">api/broadcaster</a></li><li><a href="module-api_categories.html">api/categories</a><ul class='methods'><li data-type='method'><a href="module-api_categories.html#.create">create</a></li><li data-type='method'><a href="module-api_categories.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_categories.html#.getAllWithParentId">getAllWithParentId</a></li><li data-type='method'><a href="module-api_categories.html#.getById">getById</a></li><li data-type='method'><a href="module-api_categories.html#.update">update</a></li></ul></li><li><a href="module-api_challenges.html">api/challenges</a><ul class='members'><li data-type='member'><a href="module-api_challenges.html#.choice">choice</a></li><li data-type='member'><a href="module-api_challenges.html#.choiceRecognition">choiceRecognition</a></li><li data-type='member'><a href="module-api_challenges.html#.feedback">feedback</a></li><li data-type='member'><a href="module-api_challenges.html#.feedbackSpeech">feedbackSpeech</a></li><li data-type='member'><a href="module-api_challenges.html#.pronunciation">pronunciation</a></li><li data-type='member'><a href="module-api_challenges.html#.pronunciationAnalysis">pronunciationAnalysis</a></li><li data-type='member'><a href="module-api_challenges.html#.speech">speech</a></li><li data-type='member'><a href="module-api_challenges.html#.speechRecording">speechRecording</a></li></ul></li><li><a href="module-api_challenges_choice.html">api/challenges/choice</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_choice.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_choice.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_choice.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_choice_recognition.html">api/challenges/choice/recognition</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.prepareChallenge">prepareChallenge</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recognise">recognise</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recogniseAudioStream">recogniseAudioStream</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recogniseNonStreaming">recogniseNonStreaming</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#~url">url</a></li></ul></li><li><a href="module-api_challenges_feedback.html">api/challenges/feedback</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_feedback.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_feedback.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_feedback.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_feedback_speech.html">api/challenges/feedback/speech</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.feedback">feedback</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.listenAndReply">listenAndReply</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.pause">pause</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.resume">resume</a></li></ul></li><li><a href="module-api_challenges_pronunciation.html">api/challenges/pronunciation</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_pronunciation.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.deleteChallenge">deleteChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_pronunciation_analysis.html">api/challenges/pronunciation/analysis</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.alignChallenge">alignChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.endStreamAudio">endStreamAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepareAudio">prepareAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepareChallenge">prepareChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.streamAudio">streamAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#~url">url</a></li></ul></li><li><a href="module-api_challenges_speech.html">api/challenges/speech</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_speech.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_speech.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_speech.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_speech_recordings.html">api/challenges/speech/recordings</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.record">record</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#~url">url</a></li></ul></li><li><a href="module-api_communication.html">api/communication</a><ul class='members'><li data-type='member'><a href="module-api_communication.html#.settings">settings</a></li><li data-type='member'><a href="module-api_communication.html#~APPLICATION_JSON">APPLICATION_JSON</a></li><li data-type='member'><a href="module-api_communication.html#~AUTHORIZATION">AUTHORIZATION</a></li><li data-type='member'><a href="module-api_communication.html#~CONTENT_TYPE">CONTENT_TYPE</a></li><li data-type='member'><a href="module-api_communication.html#~LINK">LINK</a></li></ul><ul class='methods'><li data-type='method'><a href="module-api_communication.html#.addAccessToken">addAccessToken</a></li><li data-type='method'><a href="module-api_communication.html#.authorisedRequest">authorisedRequest</a></li><li data-type='method'><a href="module-api_communication.html#.request">request</a></li><li data-type='method'><a href="module-api_communication.html#.updateSettings">updateSettings</a></li><li data-type='method'><a href="module-api_communication.html#~getBearerToken">getBearerToken</a></li><li data-type='method'><a href="module-api_communication.html#~handleResponse">handleResponse</a></li></ul></li><li><a href="module-api_communication_websocket.html">api/communication/websocket</a><ul class='methods'><li data-type='method'><a href="module-api_communication_websocket.html#.closeWebsocketConnection">closeWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.getWebsocketConnection">getWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.makeWebsocketCall">makeWebsocketCall</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.openWebsocketConnection">openWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#~establishNewBundesbahn">establishNewBundesbahn</a></li><li data-type='method'><a href="module-api_communication_websocket.html#~handleWebsocketAuthorisationChallenge">handleWebsocketAuthorisationChallenge</a></li></ul></li><li><a href="module-api_emailauth.html">api/emailauth</a><ul class='methods'><li data-type='method'><a href="module-api_emailauth.html#.create">create</a></li><li data-type='method'><a href="module-api_emailauth.html#~url">url</a></li></ul></li><li><a href="module-api_groups.html">api/groups</a><ul class='methods'><li data-type='method'><a href="module-api_groups.html#.create">create</a></li><li data-type='method'><a href="module-api_groups.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_groups.html#.getById">getById</a></li></ul></li><li><a href="module-api_organisations.html">api/organisations</a><ul class='methods'><li data-type='method'><a href="module-api_organisations.html#.create">create</a></li><li data-type='method'><a href="module-api_organisations.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_organisations.html#.getById">getById</a></li></ul></li><li><a href="module-api_profile.html">api/profile</a><ul class='methods'><li data-type='method'><a href="module-api_profile.html#.create">create</a></li><li data-type='method'><a href="module-api_profile.html#.getById">getById</a></li><li data-type='method'><a href="module-api_profile.html#.getCurrent">getCurrent</a></li><li data-type='method'><a href="module-api_profile.html#~url">url</a></li></ul></li><li><a href="module-api_progress.html">api/progress</a><ul class='methods'><li data-type='method'><a href="module-api_progress.html#.getById">getById</a></li></ul></li><li><a href="module-api_roles.html">api/roles</a><ul class='methods'><li data-type='method'><a href="module-api_roles.html#.create">create</a></li><li data-type='method'><a href="module-api_roles.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_roles.html#.getById">getById</a></li></ul></li><li><a href="module-api_tenants.html">api/tenants</a><ul class='methods'><li data-type='method'><a href="module-api_tenants.html#.create">create</a></li><li data-type='method'><a href="module-api_tenants.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_tenants.html#.getById">getById</a></li></ul></li><li><a href="module-api_users.html">api/users</a><ul class='methods'><li data-type='method'><a href="module-api_users.html#.create">create</a></li><li data-type='method'><a href="module-api_users.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_users.html#.getById">getById</a></li><li data-type='method'><a href="module-api_users.html#.getCurrent">getCurrent</a></li></ul></li><li><a href="module-api_utils.html">api/utils</a><ul class='methods'><li data-type='method'><a href="module-api_utils.html#.asyncBlobToArrayBuffer">asyncBlobToArrayBuffer</a></li><li data-type='method'><a href="module-api_utils.html#.checkAudioIsNotEmpty">checkAudioIsNotEmpty</a></li><li data-type='method'><a href="module-api_utils.html#.dataToBase64">dataToBase64</a></li></ul></li><li><a href="module-api_utils_audio-over-socket.html">api/utils/audio-over-socket</a><ul class='methods'><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.encodeAndSendAudioOnDataAvailable">encodeAndSendAudioOnDataAvailable</a></li><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.prepareServerForAudio">prepareServerForAudio</a></li><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.registerStreamForRecorder">registerStreamForRecorder</a></li></ul></li></ul><h3>Classes</h3><ul><li><a href="module-api.Itslanguage.html">Itslanguage</a></li></ul><h3>Events</h3><ul><li><a href="broadcaster.html#event:websocketserverreadyforaudio">websocketserverreadyforaudio</a></li></ul> </nav> <div id="main"> <section class="package"> <h3> </h3> </section> <section class="readme"> <article><h1>ITSLanguage API Package</h1> <p>Speech technology for language education. 📣</p> <p>The JavaScript API package aims to help our customers to build applications for the <a href="https://www.itslanguage.nl">ITSLanguage</a> platform. It provides an easy interface to communicate with our <a href="https://itslanguage.github.io/itslanguage-docs">REST and WebSocket API</a>. For that purpose we made use of many ES2015 features. Also Promises notation is used a lot to help dealing with asynchronous code.</p> <h2>Requirements</h2> <p>The JavaScript API package was build with the browser in mind. However any JavaScript project can use this package to build applications for the ITSLanguage platform. There are of course a few things to keep in mind when not developing for the browser. Our own development on this package is based on browser usage. We don't extensively test on other platforms. Do let us know if something is not working by using the <a href="https://github.com/itslanguage/itslanguage-js/issues">issue tracker</a>. And of course, we accept pull requests!</p> <p>ITSLanguage JavaScript API package uses:</p> <ol> <li><a href="https://developer.mozilla.org/en/docs/Web/API/Fetch_API">The <code>fetch</code> API</a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams">URLSearchParams</a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/FormData">FormData</a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSocket">WebSocket</a></li> </ol> <p>It is expected that these are accessible through their <code>global</code> accessors (i.e. by simply calling <code>new FormData()</code>, <code>fetch(...)</code>, etc.).</p> <p>Modern browsers support these (at least to the capacity we use it). Older browsers as well as <code>Node</code> don't necessarily support these because the are, as of writing this, still seen as experimental (browser) features. They are living standards and therefore expected to be implemented in the future.</p> <p>In the mean time; you might want to look at a few libraries which will add these APIs to your environment. Here are a few we found useful.</p> <h3>Browser</h3> <ul> <li><a href="https://www.npmjs.com/package/whatwg-fetch">whatwg-fetch</a></li> <li><a href="https://www.npmjs.com/package/url-search-params-polyfill">url-search-params-polyfill</a></li> </ul> <h3>Node.js</h3> <ul> <li><a href="https://www.npmjs.com/package/node-fetch">node-fetch</a></li> <li><a href="https://www.npmjs.com/package/url-search-params">url-search-params</a></li> <li><a href="https://www.npmjs.com/package/form-data">form-data</a></li> </ul> <h4>Both</h4> <ul> <li><a href="https://www.npmjs.com/package/isomorphic-fetch">isomorphic-fetch</a></li> </ul> <h2>Installation</h2> <p>The ITSLanguage Javascript API pacakge will be distributed as a <a href="https://npmjs.org/package/@itslanguage/api">npm package</a>. Package managers that can read this registry (like <a href="https://www.npmjs.com/get-npm">npm</a> and <a href="https://yarnpkg.com">yarn</a>) can be used to add the api to your project's package.json file. For simplicity this readme assumes <a href="https://www.npmjs.com/get-npm">npm</a> as package manager.</p> <p>Adding the api package into your project is as easy as instructing <a href="https://www.npmjs.com/get-npm">npm</a> to do so. This will automatically add an entry in your package.json file. If not, you are probably using an older <a href="https://www.npmjs.com/get-npm">npm</a> version (< 5.x). Consider upgrading to at least > 5.x.</p> <pre class="prettyprint source lang-shell"><code>npm install @itslanguage/api </code></pre> <p><strong>note</strong>: While we describe usage like installing packages through <a href="https://www.npmjs.com/get-npm">npm</a>, the ITSLanguage SDK itself has been build as a so called monorepository managed by <a href="https://yarnpkg.com/blog/2017/08/02/introducing-workspaces">yarn workspaces</a>. The api package is a package inside the ITSLanguage SDK. For using the api package in your project <a href="https://yarnpkg.com">yarn</a> is not a requirement! You can use the package manager which is most comfortable for you and your project.</p> <p><strong>note</strong>: The API packages is also published as an UMD bundle via <a href="https://unpkg.com">unpkg.com</a>. This makes it possible to install or download the packages <em>without</em> <a href="https://www.npmjs.com/get-npm">npm</a>. All needed dependencies will also be bundled for convenience. See the example below to get an idea on how to use it.<br> We do recommend usage with a package manager like <a href="https://www.npmjs.com/get-npm">npm</a> or <a href="https://yarnpkg.com">yarn</a> though. The examples that follow asume you've installed the api package with <a href="https://www.npmjs.com/get-npm">npm</a></p> <pre class="prettyprint source lang-html"><code><!DOCTYPE html> <html> <head> <title>Some page title</title> <script src="https://unpkg.com/@itslanguage/api@v5.0.0/dist/api.min.js"></script> <script> // The api is now available through global `itslApi`. itslApi.createItslApi(); </script> </head> <body> Hello, world! </body> </html> </code></pre> <h2>Usage</h2> <p>At its highest level one can import a factory method to instantiate the api. The object created can then be used to access all other api package functions. For us this has been found the most common use case. It is possible of course to import specific features at your own need.</p> <p>So the next code snippet will demonstrate all you need to import to get started.</p> <pre class="prettyprint source lang-js"><code>// Import the api package import { createItslApi } from '@itslanguage/api'; // Instantiate the api object const itslApi = createItslApi(); </code></pre> <h3>Pre-requirements</h3> <p>To be able to communicate with our backend servers it is (obviously) required to know the url's to connect to. As part of a user registration we will provide you with the details to get started with. For demonstration purposes we use the following details:</p> <p>Connection details</p> <ul> <li>REST API url: https://api.itslanguage.io (url does not exist, just here for demo purposes!)</li> <li>WebSocket API url: wss://ws.itslanguage.io (url does not exist, just here for demo purposes!)</li> </ul> <p>Authentication details</p> <ul> <li>Tenant: <code>demo-tenant</code></li> <li>Organisation: <code>demo-school</code></li> <li>Student user: <code>student</code></li> <li>Student password: <code>student</code></li> </ul> <h3>Example: authenticate as a student</h3> <p>Authentication to our backend means you need to get an access token. This token can then be used to perform certain actions, based on the permission a certain role has. Each user has one or more roles.</p> <p>For more information about <a href="https://itslanguage.github.io/itslanguage-docs/api/roles/index.html">roles</a>, <a href="https://itslanguage.github.io/itslanguage-docs/api/permissions/index.html">permissions</a> and or <a href="https://itslanguage.github.io/itslanguage-docs/api/oauth2/index.html">access tokens</a> consult our API docs.</p> <p>You can use the api to obtain the access token, or you can pass the access token yourself to the factory function. In the next example we will instruct the api to get the token for us. The api will then store the token so next requests will automatically use the previously obtained token.</p> <pre class="prettyprint source lang-js"><code>import { createItslApi } from '@itslanguage/api'; // Prepare the options const options = { apiUrl: 'https://api.itslanguage.io', wsUrl: 'wss://ws.itslanguage.io', }; // Instantiate the api object const itslApi = createItslApi(options); // Prepare a user scope const scope = itslApi.authentication.assembleScope( 'demo-tenant', 'demo-school', 'student', ); // Authenticate to our backend, returns a promise const auth = itslApi.authentication.authenticate( 'student', 'student-password', scope, ); auth.then(authResult => { console.log(authResult); // Will output the token, user and scope for the user obtained. }); </code></pre> <h3>Example: get current user details</h3> <p>As said in the previous example, it is also possible to pass a previously obtained token to the api. Lets get the current user details from the server.</p> <p>For more information about the <a href="https://itslanguage.github.io/itslanguage-docs/api/users/index.html#get-current-user">current user</a> consult our API docs.</p> <p>The following example presumes the token to use is <code>wubbaLubbaDubDub-token</code>. This token is already valid for a user with a valid scope.</p> <pre class="prettyprint source lang-js"><code>import { createItslApi } from '@itslanguage/api'; // Prepare the options const options = { apiUrl: 'https://api.itslanguage.io', wsUrl: 'wss://ws.itslanguage.io', authorizationToken: 'wubbaLubbaDubDub-token', }; // Instantiate the api object const itslApi = createItslApi(options); itslApi.users.getCurrent().then(currentUser => { console.log(currentUser); // Will output the details of the current user. }); </code></pre></article> </section> </div> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Mon Oct 12 2020 12:26:34 GMT+0000 (Coordinated Universal Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme. </footer> <script>prettyPrint();</script> <script src="scripts/polyfill.js"></script> <script src="scripts/linenumber.js"></script> <script src="scripts/search.js" defer></script> </body> </html>