https://github.com/spectrocloud/hello-universe-api
A Spectro Cloud demo application. This is the API server for the Hello Universe app.
https://github.com/spectrocloud/hello-universe-api
Last synced: 5 months ago
JSON representation
A Spectro Cloud demo application. This is the API server for the Hello Universe app.
- Host: GitHub
- URL: https://github.com/spectrocloud/hello-universe-api
- Owner: spectrocloud
- License: mpl-2.0
- Created: 2022-12-29T15:16:17.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-01-02T16:16:50.000Z (6 months ago)
- Last Synced: 2026-01-08T20:44:51.255Z (5 months ago)
- Language: Go
- Size: 883 KB
- Stars: 2
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/semantic-release/semantic-release)
# Hello Universe API
A Spectro Cloud demo application. This is the API server for the [Hello Universe](https://github.com/spectrocloud/hello-universe) app.
# Overview
The [Hello Universe](https://github.com/spectrocloud/hello-universe) app includes an API server that expands the capabilities of the application. The API server requires a Postgres database to store and retrieve data. Use the [Hello Universe DB](https://github.com/spectrocloud/hello-universe-db) container for simple integration with a Postgres database.
# Endpoints
A Postman collection is available to help you explore the API. Review the [Postman collection](./tests/postman_collection.json) to get started.
# Prerequisites
Ensure [Docker Desktop](https://www.docker.com/products/docker-desktop/) on your local machine is available.
- Use the following command and ensure you receive an output displaying the version number.
```shell
docker version
```
Alternatively, you can install [Podman](https://podman.io/docs/installation).
- If you are not using a Linux operating system, create and start the Podman Machine in your local environment. Otherwise, skip this step.
```shell
podman machine init
podman machine start
```
- Use the following command and ensure you receive an output displaying the installation information.
```shell
podman info
```
# Usage
The quickest method to start the API server locally is by using the Docker image.
```shell
docker pull ghcr.io/spectrocloud/hello-universe-api:1.1.0
docker run -p 3000:3000 ghcr.io/spectrocloud/hello-universe-api:1.1.0
```
If you choose Podman, you can use the following commands.
```shell
podman pull ghcr.io/spectrocloud/hello-universe-api:1.1.0
podman run -p 3000:3000 ghcr.io/spectrocloud/hello-universe-api:1.1.0
```
To start the API server you must have connectivity to a Postgres instance. Use [environment variables](#environment-variables) to customize the API server start parameters.
## Environment Variables
The API server accepts the following environment variables.
| Variable | Description | Default |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `PORT` | The port number the application will listen on. | `3000` |
| `HOST` | The host value name the API server will listen on. | `0.0.0.0` |
| `DB_NAME` | The database name. | `counter` |
| `DB_USER` | The database user name to use for queries. | `postgres` |
| `DB_HOST` | The hostname or url to the database. | `0.0.0.0` |
| `DB_PASSWORD` | The database password. | `password` |
| `DB_ENCRYPTION` | The Postgres [ssl mode](https://www.postgresql.org/docs/current/libpq-ssl.html) behavior to enable. Allowed values are: `require`, `verify-full`, `verify-ca`, or `disable` | `disable` |
| `DB_INIT` | Set to `true` if you want the API server to create the required database schema and tables in the target database. | `false` |
| `AUTHORIZATION` | Set to `true` if you want the API server to require authorization tokens in the request. | `false` |
## Authorization
The API can be enabled with authorization which results in all requests requiring an authorization header with a token. An anonymous token is available:
```shell
931A3B02-8DCC-543F-A1B2-69423D1A0B94
```
To enable authorization for the API set the environment variable `AUTHORIZATION` to `true`.
Ensure all API requests have an `Authorization` header with the Bearer token.
```shell
curl --location --request POST 'http://localhost:3000/api/v1/counter' \
--header 'Authorization: Bearer 931A3B02-8DCC-543F-A1B2-69423D1A0B94'
```
> [!NOTE]
>
> Authorization does not apply to the `/health` endpoint.
## Image Verification
We sign our images through [Cosign](https://docs.sigstore.dev/signing/quickstart/). Review the [Image Verification](./docs/image-verification.md) page to learn more.