HBO-ICT.Cloud Documentation

Introductie

Deze documentatie is bedoeld om een goede beeld te krijgen van de functionaliteiten van de HBO-ICT.Cloud API!

Benieuwd naar wat je met een oudere versie* van deze API kon maken? Bekijk dan eens de FYS Workshop voor een demonstratie! Je kunt onder andere:

• Dynamisch een navigatiebalk inladen
• Onthouden of iemand is ingelogd
• Profielfotos uploaden
• E-mails sturen
• Gemakkelijk gegevens uit de URL halen of juist erin stoppen
• Queries op de database uitvoeren en de data tonen op de website

* Voor de kenners: Dit voorbeeld is geschreven in JavaScript (ES6), jullie gebruiken echter ESM modules met TypeScript!

HBO-ICT.Cloud Projectpagina

Op deze pagina wordt heel kort uitgelegd wat je met de verschillende onderdelen van je projectpagina.

Projectgegevens

In deze sectie vind je alle relevante informatie over je project, waaronder je projectcode, toegewezen gebruikers en een link naar je Git repository.

Ontwikkelomgevingen

Voor sommige projecten heb je meer dan één omgeving tot je beschikking om je website op uit te rollen. Over het algemeen bestaan de URLs van deze omgevingen uit een prefix (bijvoorbeeld dev-) gevolgd door je projectcode. De Live-omgeving is altijd zonder prefix.

Inloggegevens

Let op! De manier waarop deze API werkt is zeer onveilig en enkel bedoeld voor leerdoeleindes. Deel daarom nooit je API Key met andere studenten of personen buiten de HvA. Je kunt werk verliezen!

HBO-ICT.Cloud API

De HBO-ICT.Cloud stelt je instaat een website te bouwen met ondersteuning voor databases, bestanden en e-mails, zonder dat je zelf de backend hoeft te maken die dit normaal gesproken verzorgd.

Je kunt tegen deze API aanpraten met de bijbehorende NPM library.

Op de API Docs vind je de technische documentatie, je kunt op die website zoeken naar interessante functies. In de menu aan de linkerkant van deze pagina vind je interactieve voorbeelden.

De API Docs en interactieve voorbeelden zijn express in het Engels geschreven. Je zult op internet namelijk eerder Engelse documentatie vinden dan Nederlandse.

SFTP

Je ontwikkelomgevingen zijn middels het SFTP protocol te bewerken.

Er zijn een hoop applicaties beschikbaar om met een SFTP server te verbinden. Je hebt hiervoor het server-adres en de inloggegevens nodig die je vind op je projectpagina.

Je kunt onder andere WinSCP (Windows), FileZilla Client (Windows / Mac / Linux) of Cyberduck (Windows / Mac) gebruiken.

Een andere keus kan zijn om een browser extensie te installeren, zoals sFTP Client (Chrome) of FireFTP (Firefox).

MySQL

Je kunt op aantal verschillende manieren je MySQL databases bewerken.

• Browser
  Je kunt met je browser gebruik maken van onze phpMyAdmin installatie. Dit hoef jij dus niet zelf te installeren! Druk op de knop op je projectpagina en je wordt automatisch ingelogd.

• Tools
  Je kunt ook met andere losse tools direct met de MySQL server verbinden. Je gebruikt hiervoor de inloggegevens die je vind op je projectpagina. Voorbeelden zijn MySQL Workbench, DBeaver, HeidiSQL (Windows) en Datagrip. Voor deze laatste heb je een studentenlicentie van Jetbrains nodig, dat kun je hier doen door je HvA e-mailadres te gebruiken.

• VSCode Extension
  Het extensie-ecosysteem van VSCode is gigantisch! Er zijn een tweetal extensies die prima werken: Optie 1 en Optie 2. Het nadeel van deze extensies is wel dat je veel meer zelf moet doen door alle queries zelf te schreven (zelfs het aanmaken van tabellen).

Online Kennissessies

Tijdens de onlinedagen worden er nuttige kennissessies opgenomen, waaronder een aantal over het gebruik van de startprojecten, HBO-ICT.Cloud, enzovoorts.

Project SE: Code Exchange

Onderstaande YouTube playlist bevat zowel compleet nieuwe als oudere videos van vorig jaar.

De oudere video's kunnen in sommige gevallen nog naar Dokkie (Blok 1) refereren, dit komt omdat studenten vorig jaar in Blok 1 al met de HBO-ICT.Cloud aan de gang gingen!

Daarnaast is het enige verschil dat sommige voorbeelden eerst in JavaScript worden geschreven en daarna pas in TypeScript. Ook dat komt omdat studenten vorig jaar in Blok 1 nog konden kiezen tussen beide varianten.

Je kunt onderstaande video's in principe in elke volgorde kijken.

Voor de uitrol naar de HBO-ICT.Cloud komt nog een apart artikel in de HBO-ICT Knowledgebase!

Project SE: Dokkie

TypeScript Bytes

Speciaal voor de HvA heeft Lennard een videoserie opgenomen om het programmeren met TypeScript toe te lichten.

Deze videoserie is in de basis bedoeld voor beginnende programmeurs, maar het is ook zeker voor studenten die al wat ervaring hebben. Sterker nog, we raden aan gewoon alles eens te kijken, wellicht leer je nog iets wat je nog niet wist!

De videos zijn ongeveer 10 minuten per stuk en behandelen een los onderdeel per keer. Over de komende tijd zullen er steeds meer videos beschikbaar komen en langzaam toewerken naar hoe je TypeScript gebruikt om websites te bouwen.

Courses & Links

Op deze pagina een paar nuttige links.

Links

• Boek: UML Distilled - Third Edition
• Tool: UMLet

Course: Object Oriented Programming met TypeScript

Bron: https://www.linkedin.com/learning/typescript-object-oriented-programming/

Korte cursus over object-georiënteerd programmeren in TypeScript

In hoofdstuk 2 kun je de videos over Generics en Polymomorphism overslaan (voor blok 2). Alle SE-ers worden geadviseerd om deze cursus te doen en mee te typen. In de video's worden niet altijd de datatypes expliciet opgegeven. Onze linter is zo ingesteld dat jullie dat wel moeten doen.

Course: Object Oriented Programming in het algemeen

Bron: https://www.linkedin.com/learning/programming-foundations-object-oriented-design-3/

Cursus met uitleg over objectorientatie, programmeertaalonafhankelijk. Deze cursus kan helpen als je object-orientatie lastig vind om te begrijpen.

Hoofstukken die kunnen helpen: hoofdstuk 1, 2, 5 en 6

Course: Databases

Bron: https://www.linkedin.com/learning/programming-foundations-databases-2/

Setup

Getting started with the HBO-ICT.Cloud API is as simple as installing its NPM package!

In most cases, the projects you are working with that require the HBO-ICT.Cloud API will already have this package installed. But it never hurts to check!

Checking for an already installed package

Open up your package.json and look for "@hboictcloud/api": "1.0.0" under dependencies. It can be your package is already at a newer version than 1.0.0, don't change it if that is the case!

Manually installing the package

If you don't see the package, you can install it yourself by running the following command:
npm install @hboictcloud/api --registry=https://registry.hbo-ict.cloud/

The --registry is required, unless you have a .npmrc file that contains this registry already. This is because the NPM package is not hosted on the global NPM registry.

After this, you are good to go! Don't forget to always run npm install again if you make changes to your dependencies in package.json.

Configuration

Configuration is the first thing you have to do before you can even start using the HBO-ICT.Cloud API component of the NPM package.

This is what all properties do:

• API-URL: The endpoint of the FYS.Cloud API, you can find this on your project-page.
• API-Key: A special kind of username/password used to communicate with the FYS.Cloud API, you can find this on your project-page.
• Database-name: The name of the database you would like to use in your SQL queries by default.
• Environment-name: The environment you would like to upload files to.

Dynamic example

Note! Changing these fields will also update the code example below! It is also required to fill out these fields accordingly if you want to try the dynamic examples on other pages!

Code example

import { api } from "@hboictcloud/api"

api.configure({
    url: "API-URL",
    apiKey: "API-Key",
    database: "Database-name",
    environment: "Environment-name"
});

Multiple environments

Some projects will have more than one enviroment, the default always being live. Be sure you adjust your configuration accordingly when deploying your project. An easy way to do this is by using .env-files.

Querying a database

Browsers cannot directly talk SQL to a database, you need something to do the talking for you. The HBO-ICT.Cloud API is that something.

Dynamic example

Note! You need to submit your HBO-ICT.Cloud configuration before this example will work!

Also see this for more information on querying a database.

No result yet!

Code example

Note! Variables should be replaced with question marks (?) in queries! Do not use string concatenation, as this imposes a security risk called SQL injection!

import { api } from "@hboictcloud/api";

async function main(): Promise<void> {
    try {
        const result: Array<any> = (await api.queryDatabase(
            "SELECT * FROM test WHERE name = ? and age <= ?",
            "Lennard", 30
        )) as Array<any>;

        console.log(result);
    }
    catch(reason) {
        console.log(reason);
    }
}

main();

import { api } from "@hboictcloud/api";

async function main() {
    try {
        const data = await api.queryDatabase(
            "SELECT * FROM test WHERE name = ? and age <= ?",
            "Lennard", 30
        );

        console.log(data);
    }
    catch(reason) {
        console.log(reason);
    }
}

main();

Sending e-mails

Unfortunately, browsers also cannot talk directly to a SMTP-Server to send e-mails. So the HBO-ICT.Cloud API took care of that for you!

Dynamic example

Note! You need to submit your HBO-ICT.Cloud configuration before this example will work!

Code example

Also see this documentation for more information on the email-format. It's also possible to send multiple attachments!

Note! The value of address on from will always be overriden with yourprojectcode@hbo-ict.cloud to prevent and track abusive behavior. Please send e-mails reponsibly, or you will have your permissions to do so revoked.

import { api } from "@hboictcloud/api";

async function main(): Promise<void> {
    try {
        const result: string = await api.sendEmail({
            from: {
                name: "You",
                address: "you@hbo-ict.cloud"
            },
            to: [
                {
                    name: "Lennard Fonteijn",
                    address: "l.c.j.fonteijn@hva.nl"
                }
            ],
            subject: "Just a test!",
            html: "&lt;h1&gt;Hello Lennard!&lt/h1&gt;&ltp&gt;This is an email :)&lt/p&gt;"
        });

        console.log(result);
    }
    catch(reason) {
        console.log(reason);
    }
}

main();

import { api } from "@hboictcloud/api";

async function main() {
    try {
        const result = await api.sendEmail({
            from: {
                name: "You",
                address: "you@hbo-ict.cloud"
            },
            to: [
                {
                    name: "Lennard Fonteijn",
                    address: "l.c.j.fonteijn@hva.nl"
                }
            ],
            subject: "Just a test!",
            html: "<h1>Hello Lennard!&lt/h1>&ltp>This is an email :)&lt/p>"
        });

        console.log(result);
    }
    catch(reason) {
        console.log(reason);
    }
}

main();

Uploading files

Uploading files is usually quite a hassle. Luckily the HBO-ICT.Cloud API provides a bunch of useful functions to upload files and generate image previews, among other things.

Dynamic example

Note! You need to submit your HBO-ICT.Cloud configuration before this example will work!

Filename / Path: *

File:

Overwrite if exists

Upload file Delete file Delete directory List directory

* Can be a path using slashes.

No result yet!

Nothing to preview yet!

Code example - Upload a file

To upload a file you first need to get the Data-URL from the upload-field. After that succeeds, you can send it to the HBO-ICT.Cloud API for saving.

import { api, types, utils } from "@hboictcloud/api";

async function main(): Promise<void> {
    try {
        //Get the input-element
        const fileUploadInput: HTMLInputElement = document.querySelector("#fileUpload")!;

        //Generate a Data-URL
        const data: types.DataURL = (await utils.getDataUrl(fileUploadInput)) as types.DataURL;

        //Upload the data
        const result: string = await api.uploadFile("test.png", data.url);

        console.log(result);
    } catch (error) {
        console.log(error);
    }
}

main();

import { api, utils } from "@hboictcloud/api";

async function main() {
    try {
        //Get the input-element
        const fileUploadInput = document.querySelector("#fileUpload")!;

        //Generate a Data-URL
        const data = await utils.getDataUrl(fileUploadInput);

        //Upload the data
        const result: string = await api.uploadFile("test.png", data.url);

        console.log(result);
    } catch (error) {
        console.log(error);
    }
}

main();

Code example - Preview an image

The Data-URL can also be used to show a preview, but only if the uploaded file is an image!

import { types, utils } from "@hboictcloud/api";

async function main(): Promise<void> {
    try {
        //Use a selector to create a Data-URL
        const data: types.DataURL = await utils.getDataUrl("#fileUpload") as types.DataURL;
        
        //If this is an image, update the src-attribute of the image-element
        if (data.isImage) {
            (document.querySelector("#imagePreview") as HTMLImageElement).src = data.url;
        }
    } catch (reason) {
        console.log(reason);
    }
}

main();

import { utils } from "@hboictcloud/api";

async function main() {
    try {
        try {
            //Use a selector to create a Data-URL
            const data = await utils.getDataUrl("#fileUpload");

            //If this is an image, update the src-attribute of the image-element
            if (data.isImage) {
                document.querySelector("#imagePreview").src = data.url;
            }
        } catch (reason) {
            console.log(reason);
        }
    }
    catch(reason) {
        console.log(reason);
    }
}

main();

Code example - Other operations

Last but not least, you can also:

• Delete a file
• Delete an empty directory
• List the contents of a directory

Note! This is only a partial example, don't forget to use try/catch and async/await like in the previous examples!

import { api } from "@hboictcloud/api"

//Delete file test.png from the uploads-folder
api.deleteFile("test.png");

//Delete directory test from the uploads-folder, but only when it is empty!
api.deleteDirectory("test");

//List all files and directories directly inside the uploads-folder
api.listDirectory();

//List all files and directories directly inside the "users/1"-folder inside the uploads-folder
api.listDirectory("users/1");