Description

HTTP API that handles, under the hood, the e-mail us section and the Google Form of the Triennale-elettronica-polimi website.

☁️ It's hosted on Flyio. ¹
🛡️ Protected by bot via friendly captcha.
👻 Hidden secrets via enviroment variable.
⚡ Fast thanks to Go.
📬 Communicate with the Telegram API. ²

How it works

1.   It receives the form data submitted via javascript POST request from the website.
2.   Check if the data body isn't too big and malformed.
3.   Check if the captcha submission was successful. If not, send back to the client the captcha error and jump to step 6.
4.   It sends message to a Telegram BOT which will write to a private channel (here how).
5.   Check if the communication with the Telegram API was successful.
6.   Write the result on the HTTP header (200 or 406) and on the responsse to the javascript client.
7.   The Javascript client will handle the response and inform the user about the operation (inserting text on HTML).

Why redirect the HTML form to this API if JavaScript can handle HTTP requests with ease?

1. Because the Polimi website is open source, it's important for future generations of students to have access to it and the ability to make changes. However, in JavaScript, how can we hide secret variables while maintaining an open-source project? These secret variables are crucial for accessing friendly captcha protection and the Telegram chat where messages are delivered. If these secrets are exploited, it could lead to misuse of the Telegram chat and render it unusable. You can refer to discussions here and here, which focus on the server-side approach.

   But it's important to remember that Telegram is just an API endpoint, and it's entirely possible to send messages to chats from the browser as well (see here for an example). The same applies to the verification API of friendly captcha, which you can find here.

2. This API can be extended with additional features, such as the ability to directly receive files and create pull requests to the GitHub repository or even send emails to maintainers, capabilities that cannot be achieved in the browser alone. Indeed, it also handles POST requests sent from Google Forms when someone submits files to maintainers (utilizing an AppScript embedded within the form).

3. Through this API, we can filter incoming data; if the data is too large or of the wrong type, it is rejected before reaching Telegram. This serves as a security shield before sending emails or messages to maintainers.

4. _{We don't depend on external, usually not free, Cloud Automation APP, like IFTTT, but we depend on Fly.io. I personally prefer the last one, I've found external apps not so fast to send messages on Google Form/Sheet update. And with 4 Fly.io machines (2 in France, 2 in Sweden), I'm pretty sure to be covered in case of fault of one of them.}

Future development

📌 Embed the CAPTCHA validation directly into the API.

Testing

❗ Try it sending a GET request ³

curl https://formapi.fly.dev

Or if you are on a web browser, just click me.

Thanks

I would like to express my gratitude to Marius for his well-explained blog post, which served as an inspiration for my API.

Footnotes

1. Automatically deployed on master changes via Github Actions. ↩

2. The Telegram API ↩

3. You cannot send POST request as you won't send the friendly captcha verification code. ↩