summaryrefslogtreecommitdiff
path: root/api/README.md
diff options
context:
space:
mode:
authorFabian Mastenbroek <mail.fabianm@gmail.com>2021-04-25 21:53:42 +0200
committerGitHub <noreply@github.com>2021-04-25 21:53:42 +0200
commit128f76f7fd7c8abb41a3bbbd9f1980cbc20ae7a5 (patch)
treeadd513890005233a7784466797bfe6f5052e9eeb /api/README.md
parent128a1db017545597a5c035b7960eb3fd36b5f987 (diff)
parent57b54b59ed74ec37338ae26b3864d051255aba49 (diff)
build: Flatten project structure
This change updates the project structure to become flattened. Previously, the simulator, frontend and API each lived into their own directory. With this change, all modules of the project live in the top-level directory of the repository.
Diffstat (limited to 'api/README.md')
-rw-r--r--api/README.md101
1 files changed, 0 insertions, 101 deletions
diff --git a/api/README.md b/api/README.md
deleted file mode 100644
index 182cd803..00000000
--- a/api/README.md
+++ /dev/null
@@ -1,101 +0,0 @@
-<h1 align="center">
- <img src="../misc/artwork/logo.png" width="100" alt="OpenDC">
- <br>
- OpenDC Web Server
-</h1>
-<p align="center">
- Collaborative Datacenter Simulation and Exploration for Everybody
-</p>
-
-<br>
-
-The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](../opendc-api-spec.yml).
-
-This document explains a high-level view of the web server architecture ([jump](#architecture)), and describes how to set up the web server for local development ([jump](#setup-for-local-development)).
-
-## Architecture
-
-The following diagram shows a high-level view of the architecture of the OpenDC web server. Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow.
-
-![OpenDC Web Server Component Diagram](misc/artwork/opendc-web-server-component-diagram.png)
-
-The OpenDC API is implemented by the `Main Server Loop`, which is the only component in the base package.
-
-### Util Package
-
-The `Util` package handles several miscellaneous tasks:
-
-* `Database API`: Wraps database access functionality used by `Models` to read themselves from/write themselves into the database.
-* `Exceptions`: Holds definitions for exceptions used throughout the web server.
-* `Parameter Checker`: Recursively checks whether required `Request` parameters are present and correctly typed.
-* `REST`: Parses SocketIO and HTTP messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`.
-
-### API Package
-
-The `API` package contains the logic for the HTTP methods in each API endpoint. Packages are structured to mirror the API: the code for the endpoint `GET api/projects`, for example, would be located at the `endpoint.py` inside the `projects` package (so at `api/projects/endpoint.py`).
-
-An `endpoint.py` file contains methods for each HTTP method it supports, which takes a request as input (such as `def GET(request):`). Typically, such a method checks whether the parameters were passed correctly (using the `Parameter Checker`); fetches some model from the database; checks whether the data exists and is accessible by the user who made the request; possibly modifies this data and writes it back to the database; and returns a JSON representation of the model.
-
-The `REST` component dynamically imports the appropriate method from the appropriate `endpoint`, according to request it receives, and executes it.
-
-### Models Package
-
-The `models` package contains the logic for mapping Python objects to their database representations. This involves an abstract `model` which has generic CRUD operations. Extensions of `model`, such as a `User` or `Project`, specify some more specific operations and their collection metadata.
-
-`Endpoint`s import these `models` and use them to execute requests.
-
-## Setup for Local Development
-
-The following steps will guide you through setting up the OpenDC web server locally for development. To test individual endpoints, edit `static/index.html`.
-
-### Local Setup
-
-#### Install requirements
-
-Make sure you have Python 3.7+ installed (if not, get it [here](https://www.python.org/)), as well as pip (if not, get it [here](https://pip.pypa.io/en/stable/installing/)). Then run the following to install the requirements.
-
-```bash
-pip install -r requirements.txt
-```
-
-The web server also requires a running MongoDB instance. We recommend setting this up through docker, by running `docker-compose build` and `docker-compose up` in the [`mongodb` directory](../database) of the main OpenDC repository.
-
-#### Get and configure the code
-
-Clone OpenDC and follow the [instructions in the main repository](../) to set up a Google OAuth ID and environment variables.
-
-**Important:** Be sure to set up environment variables according to those instructions, in a `.env` file.
-
-If you want to test REST calls manually, add your own `OAUTH_CLIENT_ID` in `content=` on line `2` in `api/static/index.html`.
-
-#### Set up the database
-
-You can selectively run only the database services from the standard OpenDC `docker-compose` setup (in the root directory):
-
-```bash
-docker-compose build mongo mongo-express
-docker-compose up mongo mongo-express
-```
-
-This will set you up with a running MongoDB instance and a visual inspection tool running on [localhost:8082](http://localhost:8082), with which you can view and manipulate the database. Add the simulator images to the command lists above if you want to test simulation capabilities, as well.
-
-### Local Development
-
-Run the server.
-
-```bash
-cd api
-python main.py
-```
-
-When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py` in the console running the server) to see the result of your changes.
-
-#### Code Style
-
-To format all files, run `format.sh` in this directory. The script uses `yapf` internally to format everything automatically.
-
-To check if code style is up to modern standards, run `check.sh` in this directory. The script uses `pylint` internally.
-
-#### Testing
-
-Run `pytest opendc` in this directory to run all tests.