Skip to content

README.md

Latest commit

 

History

History
180 lines (140 loc) · 5.71 KB

README.md

File metadata and controls

180 lines (140 loc) · 5.71 KB

FOCA-Petstore

Dockerized Petstore example application implemented using FOCA.

Description

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 module exceptions

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!

Hint Check the FOCA documentation for further details.

Installation

Requirements

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.

Deploy app

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 with 0.0.0.0.
  • If you have changed the mapped port for the app service you will need to manually append it to localhost when you access the API (or the Swagger UI) in subsequent steps. For example, assuming you would like to run the app on port 8080 instead of the default of 80, then the app will be availabe at http://localhost:8080/.

Explore app

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

Modify app

You can make use of this example to create your own app. Just modify any or all of the following: