Dockerized Petstore example application implemented using FOCA.
The example demonstrates how FOCA sets up a fully configured Flask app when passed an appropriately formatted configuration file.
FOCA makes sure that
- the returned app instance contains all configuration parameters
- FOCA configuration parameters are validated
- requests and responses sent to/from the API endpoints configured in the Petstore OpenAPI specification are validated
- a MongoDB collection to store pets in is registered with the app
- CORS is enabled
- exceptions are handled according to the definitions in the
exceptions
dictionary in moduleexceptions
Apart from writing the configuration file, all that was left for us to do to
set up this example app was to write a very simple app entry point
module, implement the endpoint controller
logic and prepare the Dockerfile
and
Docker Compose configuration for
easy shipping/installation!
Check the FOCA documentation for further details.
Ensure you have the following software installed:
- Docker (19.03.4, build 9013bf583a)
- docker-compose (1.25.5)
- Git (2.17.1)
Indicated versions were used for developing/testing. Other versions may or may not work. Please let us know if you encounter any issues with versions newer than the listed ones.
Clone repository:
git clone https://github.com/elixir-cloud-aai/foca.git
Traverse to the Petstore app (this) directory:
cd foca/examples/petstore
Build and run services in detached/daemonized mode:
docker-compose up -d --build
Some notes:
This will build the app based on the current state of your FOCA clone. That is, any changes that you may have introduced to FOCA will be reflected in your build.
By default, the app will be build based on the latest Python version that FOCA supports. If you would like to build the FOCA image based on a different version of Python, you can set the Python image to be used as FOCA's base image by defining the environment variable
PETSTORE_PY_IMAGE
before executing the build command. For example:export PETSTORE_PY_IMAGE=3.12-slim-bookworm
In case Docker complains about port conflicts or if any of the used ports are blocked by a firewall, you will need to re-map the conflicting port(s) in the Docker Compose config. In particular, for each of the services that failed to start because of a port conflict, you will need to change the first of the two numbers listed below the corresponding
ports
keyword to some unused/open port.
That's it, you can now visit the application's Swagger UI in your browser, e.g.,:
firefox http://localhost/ui # or use your browser of choice
Some notes:
- Mac users may need to replace
localhost
with0.0.0.0
.- If you have changed the mapped port for the
app
service you will need to manually append it tolocalhost
when you access the API (or the Swagger UI) in subsequent steps. For example, assuming you would like to run the app on port8080
instead of the default of80
, then the app will be availabe athttp://localhost:8080/
.
In the Swagger UI, you may use the GET
/POST
endpoints by
providing the required/desired values based on the indicated descriptions, then
hit the Try it out!
button!
Alternatively, you can access the API endpoints programmatically, e.g., via
curl
:
-
To register a new pet:
curl -X POST \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ -d '{"name":"You","tag":"cat"}' \ 'http://localhost/pets'
-
To retrieve all registered pets:
curl -X GET \ --header 'Accept: application/json' \ 'http://localhost/pets'
-
To retrieve information on a specific pet:
curl -X GET \ --header 'Accept: application/json' \ 'http://localhost/pets/0' # replace 0 with the the pet ID of choice
-
To delete a pet: :-(
curl -X DELETE \ --header 'Accept: application/json' \ 'http://localhost/pets/0' # replace 0 with the the pet ID of choice
You can make use of this example to create your own app. Just modify any or all of the following: