A Pokemon Web API, just for fun
This REST API provides two endpoints to get information about Pokemons:
GET /pokemon/<pokemon name>
Get some basic information about a Pokemon
> http localhost:5000/pokemon/mewtwo
{
"description": "It was created by a scientist after years of horrific gene-splicing and DNA-engineering experiments.",
"habitat": "rare",
"isLegendary": true,
"name": "mewtwo"
}GET /pokemon/translated/<pokemon name>
Get some basic information about a Pokemon, with "fun translation" of its description: Yoda translation if the Pokemon's habitat is cave or it's legendary; Shakespeare translation for all other Pokemons
> http localhost:5000/pokemon/translated/mewtwo
{
"description": "Created by a scientist after years of horrific gene-splicing and dna-engineering experiments, it was.",
"habitat": "rare",
"isLegendary": true,
"name": "mewtwo"
}The easiest way to run the service is through Docker.
If you don't have Docker installed on your system, take a look here first.
This command will run a container named pokefun, listening on port 5000 (choose another port number if that one is already in use):
> docker run -d -p 5000:80 --name pokefun paolofulgoni/pokefun
Given that the Docker image is published to Docker Hub (repository paolofulgoni/pokefun), you don't have to build the image from source.
You can now call the endpoints with your tool of choice, e.g. HTTPie:
> http localhost:5000/pokemon/ditto
Do you want to see the beautiful Swagger UI and test the API from there? Then run the service in Development mode and open your browser to http://localhost:5000/swagger
> docker run -d -p 5000:80 --name pokefun -e ASPNETCORE_ENVIRONMENT=Development paolofulgoni/pokefun
To stop the service, run this command:
> docker stop pokefun
When you're done, remove the container:
> docker rm pokefun
You can easily run the service from your computer, but you'll have to compile it first. Therefore, you need to:
- Install the .NET 5 SDK
- Clone the repository locally
Then use the dotnet CLI to run the service. Make sure you're on the root folder of the project, then type:
> dotnet run --project ./src/PokeFun
This will use the Development Hosting environment, therefore you can open a browser to http://localhost:5000/swagger and have fun with the Swagger UI.
Press CTRL+C when you're done.
Make sure .NET 5 SDK is installed on your dev environment. Then just open the project with your IDE of choice.
If you want to build the project using the .NET CLI, run the following command from the project's root folder:
> dotnet build
The project contains some unit and integration tests. You can run them with the following command:
> dotnet test
IMPORTANT: integration tests actually call the external services. If you want, you can easily exclude them filtering out the Integration category:
> dotnet test --filter TestCategory!=Integration
Integration tests are excluded by the CI pipeline to avoid false test failures due to the external services. For example, FunTranslation have rate limits which can change the result of some calls.
Here below few things I'd like to do before... going to production (just kidding, it'll never happen 😁):
- Add a cache layer, since the information returned by the API is static and third-party services require it (PokeApi states this in its Fair Use Policy; FunTranslations have rate limits)
- Add HTTPS support if required (in most cases it's offloaded to a load balancer, so I disabled it)
- Add retry and circuit breaker policies to external HTTP calls
- Add an Healthcheck endpoint
- PokeApi - A RESTful API for Pokémon - GitHub repo
- FunTranslations - Translations for fun
- Poké Ball image - CC BY-SA 3.0 by Geni
- Pokémon and Pokémon character names are trademarks of Nintendo
