Skip to content

Getting Started

Requirements

Linux

  • Python may already be installed by default, but a non-recommended or compatible older version;
  • Git may already been installed, so no action needed in that case;

Macos

  • Python may already be installed by default, but a non-recommended or compatible older version;
  • Git is included via Xcode Command Line Tools.

Installation

When you create an Application in the API UP website, it will automatically create a Git repository with the simple and expected project structure and with the main settings configured for you. Every developer should clone to his/her machine.

The installation is as simple as pulling a Docker image, and that image will be ready to be used for development immediately. The API UP CLI helps you with this installation and the with the development itself.

Thus, the steps are:

  1. Check/Install Docker 28.2.2+: $ docker --version

  2. Check/Install Python 3.14+: $ python3 --version

  3. Check/Install Git: $ git --version

  4. Clone your App's Git repository: $ git clone [email protected]:api-up/$APP.git

  5. Install API UP CLI

  6. Pull the Docker image and Start the API: $ apiup check && apiup start

Project Structure

Minimum required structure

Your cloned Git repository will look like this:

your-app/                           # Name of your API Application
├── apps/
│   ├── subapp1/                    # Name of subapplications of your API (1 or more)
│   │   ├── schemas/
│   │   │   ├── Model1.yaml         # One or more Model YAML schema files
│   │   ├── __init__.py             # Python requirement
│   │   └── docs.py                 # For adding logic to Models
├── ...                             # Some tool config files
├── apiup                          # The downloaded API UP CLI tool
├── Dockerfile                      # Application-specific OS dependencies
└── requirements-app.txt            # Application-specific Python dependencies

Where you can customize the subapp1 and Model1.yaml names.

Common structure

your-app/
├── apps/
│   ├── subapp1/
│   │   ├── tests/                 # For automated tests
│   │   │   ├── __init__.py        # Python requirement
│   │   │   ├── test_docs.py       # suggestion
│   │   │   └── test_commands.py   # suggestion
│   │   ├── schemas/
│   │   │   ├── Model1.yaml
│   │   │   └── Model2.yaml
│   │   ├── __init__.py
│   │   ├── commands.py            # suggestion. as soon as get bigger, you can split into different files.
│   │   ├── docs.py
│   │   └── tasks.py               # suggestion. as soon as get bigger, you can split into different files.
│   ├── subapp2/...
├── ...
├── Dockerfile
├── README.md
└── requirements-app.txt

Development

The initial commands to get things running and starting using the API:

$ apiup start  # Start the API
$ apiup ping  # Ping the API to check it is running
$ apiup create_admin  # To create the first user and other admins
$ apiup admin  # Open the Admin UI
$ apiup stop  # Stop the Docker containers
$ apiup --help