README.md file.

README.md

-# ESAP DB
+# ESAP-DB
 
+ESAP-DB is an ESAP component providing managed database services.
+
+
+## Installation
+
+This project should be cloned in the directory containing the repositories https://git.astron.nl/astron-sdc/esap-api-gateway and https://git.astron.nl/astron-sdc/esap-gui. Once it is done, add this .env file in the esap-db/host-files directory:
+
+```
+DOMAIN=localhost
+OIDC_RP_CLIENT_SECRET=********
+DBADMIN_USER=postgres
+DBADMIN_PASSWORD=postgres
+DBPROJECT_USER=postgres
+DBPROJECT_PASSWORD=postgres
+```
+
+To check that ESAP-DB is working locally:
+
+```bash
+$ esap-db/host-files/run-tests.sh
+```
+Upon success, the tests should pass.
+
+
+## Using ESAP-DB
+
+In order to use ESAP-DB locally, you can launch the required services in a ternminal:
+
+```bash
+$ esap-db/host-files/run.sh
+```
+
+In a browser, the ESAP-DB apis can be tested at the url `http://localhost:8001/docs` or `http://localhost:8001/redoc`.
+
+The PostgreSQL administration platform `pgAdmin` can be accessed at the url `http://localhost:5050`. It can be used to view the dbadmin and dbproject1 databases.
+
+## Storing an ESAP-API request into a table.
+
+Let's create a project:
+```bash
+curl -XPOST \
+  'http://localhost:8001/api/v0/projects' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "my_project",
+    "description": "My first project 😀"
+  }'
+```
+
+In this project, let's create a dataset, i.e., a group of tables:
+```bash
+curl -XPOST \
+  'http://localhost:8001/api/v0/projects/my_project/datasets' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "my_project.my_dataset",
+    "description": "My first dataset 😃"
+  }'
+```
+
+Once the project and the dataset are created, we can store the result of an ESAP-API query into a table that belongs to the dataset that we have just created.
+```bash
+curl -X 'POST' \
+  'http://localhost:8001/api/v0/projects/my_project/esap-gateway-operations' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": {
+      "level": "raw",
+      "collection": "imaging",
+      "ra": 342.16,
+      "dec": 33.94,
+      "fov": 10,
+      "archive_uri": "apertif"
+    },
+    "table": "my_dataset.apertif_query"
+  }'
+```
+
+The new table `apertif_query` can be exported as JSON:
+```bash
+curl -X 'GET' \
+  'http://localhost:8001/api/v0/projects/my_project/datasets/my_dataset/tables/apertif_query/content' \
+  -H 'accept: application/json'
+```