Random Word API

Premise

Four years ago, I learned frontend development and I really wanted a career with Elm¹. You can read more about this in My Rust Story blogpost. At the time, I made a little demo for junior job interviews. A Speak and Spell clone. It used an API that closed the spigot (presumably costs?). This is to say that, when I needed an itch to learn RESTful API development, I had a hole to fill in and somewhere to start from.

What This Is

A RESTful API built with Axum in Rust and a personal project to dive deep into web service development. A simple, straightforward showcase of technical skill and learning – built to demonstrate capability at job interviews. Because I really want a career with Rust. As per premise: this API was primarily designed to support my Speak and Spell clone. Then, it evolved into a comprehensive learning experience.

Demo It

You can check the online demo, browse the source code, or run it with Docker.

Note that the free tier I’m using shuts down after some time of inactivity or stop serving entirely if quota is reached. You may experience slow loading times or no demo at all. In the latter case, you could run this demo in Docker. My apologies.

KISS

I knew I needed to devise the same model and response of the OG API, as a starting point, so I could use my existing app as a real world scenario to test against. The OG API used a very small response, so I treated it as a black box to reverse engineer. A methodology I find best suited for learning²: it forces one to think hard while offering a safety net. Thus, I started exactly from the response I was already parsing in Elm:

<!-- An actual response from my Random Word API -->
[
  {
    "word": "unknown",
    "definition": "not known or identified",
    "pronunciation": "/ʌnˈnoʊn/"
  }
]

The Database

I chose to use SQLite. It still offered good learning opportunities, both for the API and Rust tooling, so I was happy with going down this path. In preparation for the demo, it also meant running one less service (PostgreSQL) I can’t afford at the moment.

The OG API adopted data in JSON files. That could have been easier to implement, but what would have given in terms of learning? Moreover, I like SQL. I’ll take SQL and rely on SQLx guarantees, over learning and using ORMs³, any day of the week!

Beyond The Basics

The model, simple by design, fulfilled all app’s requirements and it allowed for a broader learning scope. Once I had an MVP in place, I sought to learn and implement more. I stumbled upon https://restfulapi.net/ and https://rust-api.dev/. Two great resources that provided guidance and ideas. Besides, I recalled that the OG API, had these weird @swagger comments: what are these!? They were all great pointers I needed to implement. To dig deep into. To extend my learning and expand my API: the middleware pattern, authentication, authorization, JWT token, and OpenAPI.

Iterate Iterate Iterate

In an iterative process, I refactored my code and added more features. I.e: adding grammatical types. I.e: future-proofing the API to accommodate additional languages and grammatical types with minimal efforts. This may seem like a pointless exercise for an API this simple with no real use, however, it was as valuable to my learning as learning best practices and patterns. It also demonstrates a forward-thinking attitude and a meticulous approach to projects. I suppose these are good things. Right!? 🖖🫣

TDD Is Not Dead

All code beyond the MVP, relied on TDD. Many confidently assert that TDD is dead, or that it was a mistake, however, I find it invaluable⁴ once the core of the code is in place. To help me refactor and add new features with confidence; almost fearlessly.

Conclusion

All things considered, I’m very happy with this learning journey. Starting from a known with simple requirements was a great choice. Especially for a curious as a cat always longing to know more person like I am. The simple model opened up a plethora of possibilities beyond the MVP. Is this enough!? Nah. Can I call myself a backend developer? This was the first step towards it and I’m way more confident and knowledgeable than when I started this project. So, final verdict: HELL YEAH! 🤟🤟🤟

Disclaimers

To keep this summary of my learning brief, I’ve only reported the main points to highlight the reasoning behind the process; rather than using a lengthy point-by-point. A technical learning summary is available in the Random Word API repository README file. I hope you like it as much as I loved learning with this project! ❤️🦀

I have sometime relied on Claude via Amazon Q Cli for boring and repetitive stuff.

Credits

Translation image by Kawalan from Noun Project used under CC BY 3.0.