Random Word API

Caution

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

My first RESTful API made with Axum. The proverbial itch to scratch to learn REST API design and development. Its main purpose, besides learning, is to be a simple API to use with my Speak and Spell app. This, however, didn't limit the extent of my learning. Au contraire, this was an opportunity to learn as much as possible about RESTful APIs, improving idiomatic Rust skills; and to learn a number of 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 and 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
• Compile-time checked queries validation with SQLx 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 Methods restrictions to control HTTP verbs and allow only what's needed on each route
  • CORS Origins restrictions to control which domains can access the API
  • 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

I put together a little demo with Docker that you can run 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 takes a while on Docker, be patient. When that's ready, 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:
• For administrative endpoints see AUTHENTICATION

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 move into the fe-elm_speakandspell directory and run the app with npm run dev
• Browse http://localhost:5173/ and enjoy

Acknowledgments

Random Word API was inspired by https://github.com/mcnaveen/random-words-api, which I used to use when developing my Speak and Spell toy project. Then they closed the spigot, because it was costing them too much. Incidentally, this is why I'm not deploying my API to production. I can't afford it.

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