Random Word API

Caution

This API is NOT meant for production usage. It's a project I used for learning purposes only!

This is my first RESTful API made with Axum. The proverbial itch to scratch to learn and implement REST API design and development with Axum. Its main purpose, besides learning, is to be a simple API to use with my Speak and Spell toy project. This, however, didn't limit the extent of my learning. In fact, this was an opportunity to learn as much as possible: REST API concepts, improving idiomatic Rust skills, and a number of, new to me, techniques, concepts, and best practices:

• CLI interface, with parameters validation, to instantiate the service
  • Use an environment file or configuration file to setup the API
• rustdoc documentation (run just doc from within the word-api-axum directory)
• Use TLS encryption (learned/removed, as it's best left to the proxy)
• User database with RBAC for users and administrative accounts
• Authentication with database credentials for administrative endpoints
• Authorization with JWT on protected administrative endpoints
• SQLx compile-time checked queries validation to prevent SQL Injections.
• Requests validation to make sure all parameters are as expected
• Extensive error handling for REST and database operations
• Appropriate HTTP status codes for each request case
• Middleware pattern with:
  • Compression for faster transfers
  • Requests time out to avoid client hanging too long
  • Security headers to apply restrictions and OWASP security list
  • Request limiting to avoid abuse
  • Body size limiting to avoid abuse
  • Requests rate limiting to avoid abuse
  • CORS restrictions to only allow certain verbs on each endpoint as needed
  • Origins to restrict API invocation from only allowed domains
  • Tracing for API logging
• Open API documentation with:
  • Swagger UI
  • Redoc
  • Scalar
  • RapiDoc
• Simple landing page made with Leptos for demo purposes
• Containerized everything with Docker for demo purposes
• Password protected OpenAPI endpoints with Nginx (user and password: admin)

Available endpoints

• /health/alive and /health/ready - Public health check endpoints
• /{lang}/random and /{lang}/{type} - Public word retrieval endpoints
• /auth - Authentication and authorization (requires admin user)
• /admin/{lang}/words - Administrative CRUD endpoints (requires auth)
• /swagger-ui, /redoc, /scalar, /rapidoc - OpenAPI documentation

See it in action

Docker compose

Until I find an inexpensive solution to host my API to peruse with Speak and Spell, I put together a little demo with Docker that you can see by following these three simple actions:

• Clone the repository: git clone https://github.com/andreacfromtheapp/random-word-api.git
• Move into the cloned repository: cd random-word-api
• Run docker compose up --build

Rust will take a while to compile on Docker, please be patient. When that's done, visit http://localhost in your web browser and enjoy.

Run locally

You could also peruse this API as if it was a deployed service:

• Clone the repository: git clone https://github.com/andreacfromtheapp/random-word-api.git
• Move into the API web service repository: cd random-word-api/word-api-axum
• Running it locally from a terminal: just run
• Using curl or similar to query the API endpoints (listed above):
  • For admin endpoints see AUTHENTICATION
  • For public endpoints run curl GET requests
  • For OpenAPI endpoints append any of the following to http://localhost:
    • /swagger-ui, /redoc, /scalar, /rapidoc

Run Elm Speak and Spell

To see this in action:

• Clone the repository: git clone https://github.com/andreacfromtheapp/random-word-api.git
• Move into the API web service repository: cd random-word-api/word-api-axum and run the API: just run
• In a new terminal window/tab move into the fe-elm_speakandspell directory and run the app with npm run dev
• Browse http://localhost:5173/

Acknowledgments

My API is inspired by https://github.com/mcnaveen/random-words-api, which I initially used to use when developing my Speak and Spell toy project. Then they closed the spigot, presumably because it was costing them too much (due to their success and free usage).

Random Word API initial code is based on Code Like a Pro in Rust; which I own and have used to learn more about Rust, after studying The Book.