Web App Demonstration

Demonstration of a GET API call/request

The fact this page is rendering is a demonstration of a GET API call. If you have ever worked with the server framework Express, this should look familiar.

Behind the scenes, the server contains the following routing for the API calls:

// `GET` route to render the homepage with Nunjucks
router.get('/', (req, res) => {
    res.render('index.njk', { data: undefined, error: undefined });
    // Ensure no result is passed
});

// In contrast, here's the `POST` route for the simple `POST` request 
// demonstration. It's in `routes/submit.js`.

app.post('/submit', (req, res) => {
    const { name } = req.body;
    res.json({ message: `Hello, ${name}! This is a POST response.` });
});

// All things with the Whisper and Twilio `POST` requests are modularized into 
// individual routes in the `routes/` directory. There are many lines of code in
// multiple directories, so in the interest of brevity, I'm not including them 
// here. For details, check out the source code on GitHub.

When the user navigates to the base directory (/), the backend is serving a Nunjucks template to render to HTML in the browser via a GET API call.

1: A simple POST API call/request

2: A more complex POST request (disabled)

This demo is currently disabled. The write-up below describes what it did.

This part is a bit more interesting. I'm particularly interested in text-to-speech and speech-to-text work. I've had a lot of fun playing around with Whisper by OpenAI. You may know them as the makers of ChatGPT. Whisper is a pretty advanced, at least for the general public, way to build transcription features into applications. You uploaded a file of someone talking and it transcribed it.

3: POST call lookup using Twilio (disabled)

This demo is currently disabled. The write-up below describes what it did.

You entered a telephone number and it returned the carrier.

Details on the client-side JavaScript

We all love the server side. But I started in web development as a front-end developer. I wanted to make my websites look nice and load quickly. So you aren't getting out of here without me showing off some of the client side stuff going on.

The JavaScript working on the front end to tie it all together and improve user experience. The technique we’re employing here is called AJAX,¹ and it’s pretty much manadatory for any kind of UX I’d want to create.

That’s a technique that enables sites to update without a full reload. Without it, all this would still work—you’d just be taken over to a new, separate page with the options to copy or download the file. I think it's nicer when it just populates right there.

The listing below is the handler for the transcription demo, which is disabled. It stays here because it’s the clearest example of the technique.

document.getElementById('transcription-form').addEventListener('submit', async function(event) {
    event.preventDefault();

    const formData = new FormData(this);

    try {
        const response = await fetch('/transcribe', {
            method: 'POST',
            body: formData
        });
        const result = await response.json();

        if (result.transcription) {
            document.getElementById('transcription-text').textContent = result.transcription;
            document.getElementById('download-link').href = `/download-transcription/${result.fileName}`;
            document.getElementById('transcription-result').style.display = 'block';
        } else {
            document.getElementById('transcription-text').textContent = 'Transcription failed. Please try again.';
            document.getElementById('transcription-result').style.display = 'block';
        }
    } catch (error) {
        console.error('Error:', error);
        document.getElementById('transcription-text').textContent = 'An error occurred. Please try again later.';
        document.getElementById('transcription-result').style.display = 'block';
    }
});

You can also dive in by “inspecting” this page with your browser’s developer tools. On any browser, right click and select an option that should be something like “Inspect” or “Inspect this webpage,” “Inspect element,” etc.) Alternatively, you can review the code on the GitHub repo in the public/js/main.js file, which is the public JavaScript file loaded globally by the app.

Notes

1. AJAX (Asynchronous JavaScript and XML) is a way to (among many other things) go back and forth with servers in such a way that it allows parts of a page to update without a full reload. In this application, AJAX handled the “form submissions” (uploading that file and returning the transcription). When you submitted that form, AJAX shot it to the server in the background. While nobody was looking 😆, the page updated dynamically and it was just right there! The simple POST demo above still works this way; the transcription one is disabled.