Update documentation to v2

A request looks like this:

`GET` https://status.fsco.li/api/v1/services

`GET` https://status.fsco.li/api/v2/status

And a response like this:

```json

[

  {

        "name": "Website",

        "host": "fachschaft.cl.uni-heidelberg.de",

        "status": 200,

        "category": "public"

    "name": "Automation",

    "host": "automation.fachschaft.cl.uni-heidelberg.de",

    "category": "fachschaft",

    "expectUnauthorized": true,

    "status": 401

  },

  {

        "name": "Tickets",

        "host": "tickets.fachschaft.cl.uni-heidelberg.de",

        "status": 404,

        "category": "public"

    "name": "Framadate",

    "host": "framadate.fachschaft.cl.uni-heidelberg.de",

    "category": "fachschaft",

    "status": 200

  }

]

```

```

.

├── 📁 api

│   └── 📁 v1

│   └── 📁 v2

│       ├── 📄 index.html

│       └── 📋 openapi-spec.yaml

└── 📁 lib

        └── 📄 redoc.standalone.js.LICENSE.txt

```

The file `api/v1/openapi-spec.yaml` contains a description of the API in a machine-readable format (namely the OpenAPI format). This can be rendered by various tools, e.g., the Swagger Editor or Redoc, or the GitLab-integrated viewer.

The file `api/v2/openapi-spec.yaml` contains a description of the API in a machine-readable format (namely the OpenAPI format). This can be rendered by various tools, e.g., the Swagger Editor or Redoc, or the GitLab-integrated viewer.

Of course, displaying them is not the only thing you can do with OpenAPI files. You could also validate check for consistency, or even automatically generate clients and servers for a given API as described in such a file.

The `api/v1/index.html` and everything in `lib/redoc` is static code that renders the OpenAPI specification for a visitor. This means you can comfortably look at the API at https://status.fsco.li/api/v1.

The `api/v2/index.html` and everything in `lib/redoc` is static code that renders the OpenAPI specification for a visitor. This means you can comfortably look at the API at https://status.fsco.li/api/v2.

- [Swagger Editor](https://editor.swagger.io/)

- [Redoc](https://redocly.github.io/redoc/)

.

└── 📁 api

    ├── 🔑 .htaccess

    └── 📁 v1

    └── 📁 v2

        ├── 🔑 .htaccess

        └── 🐘 services.php

        ├── 🧩 services.json

        └── 🐘 status.php

```

The main part of the server-side code is `api/v1/services.php`. Whenever a client makes a request to the server at this path, the server executes the PHP code. The PHP code can then output things (using `echo`) which are sent back to the client. Unlike static files (that are sent to the client in verbatim), the actual code contained in the PHP file is never sent back to the client[^1].

The main part of the server-side code is `api/v2/status.php`. Whenever a client makes a request to the server at this path, the server executes the PHP code. The PHP code can then output things (using `echo`) which are sent back to the client. Unlike static files (that are sent to the client in verbatim), the actual code contained in the PHP file is never sent back to the client[^1].

The code itself sends HTTPS requests to the different services to see if they are up and crafts the JSON response as described in the OpenAPI specification.

The `.htaccess` files are configuration for the Apache webserver:

- `api/.htaccess` redirects every request to `/api` to `/api/v1` (so you can enter https://status.fsco.li/api in your browser and are automatically directed to https://status.fsco.li/api/v1). This is just a comfort feature.

- `api/v1/.htaccess` rewrites every request to `/api/v1/services` to go to `/api/v1/services.php`.

- `api/.htaccess` redirects every request to `/api` to `/api/v2` (so you can enter https://status.fsco.li/api in your browser and are automatically directed to https://status.fsco.li/api/v2). This is just a comfort feature.

- `api/v2/.htaccess` rewrites every request to `/api/v2/status` to go to `/api/v2/status.php`.

    - This is necessary because we want to provide a true REST-API experience (where all the request URLs look like paths), so we would like to avoid the `.php` suffix.

### Docker

### Why the convoluted directory structure for the API?

Why is the PHP code located in `/api/v1/services.php` and not simply in a file `/services.php`?

Why is the PHP code located in `/api/v2/services.php` and not simply in a file `/services.php`?

First, it is common to separate the API routes of a web application from the routes that e.g. serve the frontend, therefore `/api/`.

Second, you should version your API, e.g. using Semantic Versioning (version numbers in the format `MAJOR.MINOR.PATCH`, e.g. `1.0.0`). It is then common to add the major version number to the API path. If you make incompatible changes to your API, you increase the major version number. This allows you to easily keep the old version of the API as long as some clients still need it. Therefore `v1/`.

Second, you should version your API, e.g. using Semantic Versioning (version numbers in the format `MAJOR.MINOR.PATCH`, e.g. `1.0.0`). It is then common to add the major version number to the API path. If you make incompatible changes to your API, you increase the major version number. This allows you to easily keep the old version of the API as long as some clients still need it. This has already happened once, hence the `v2/` folder (the old API is still available at `v1/`).

This is why we have chosen a more convoluted-looking directory structure instead of just placing the file at root level.