examples

AWS S3 Aidbox integration example

This guide demonstrates how to integrate S3-compatible storage with Aidbox using local min.io and a front-end application exclusively.

The application enables saving and retrieving a patient’s photo in an AWS S3 bucket via Aidbox, which acts as a middleware between the front-end and AWS S3. Aidbox manages the Access Key ID and Secret Access Key for an IAM user or role through an AwsAccount resource.

Setting Up Aidbox

Clone the repository

git clone git@github.com:Aidbox/examples.git

Change the directory to the current example.
Start Aidbox, AidboxDB, and min.io.
```
docker compose up
```
Go to http://localhost:9001 and log in to min.io using username minioadmin and password minioadmin.
In Object Browser, click on the “Create Bucket” link. Create a bucket with “mybucket” name.
In the navigation, click on Access Keys section. Create Access Key. Copy Access Key and Secret Key.
Go to http://localhost:8888 and log in to Aidbox using the Aidbox Portal (See Getting Started Guide):
Create an AwsAccount resource to store AWS credentials and region settings: ```http PUT /AwsAccount/my-account

id: my-account access-key-id: # e.g. ugQPrWcctDQuzdAzufXh secret-access-key: # e.g. bUqJWhOimudbEGUHj3indSnAULtwqpwqBOnqO6Rm region: us-east-1 host: 127.0.0.1:9000 path-style: true use-ssl: false

9. **Set up a [Basic Client](https://docs.aidbox.app/modules/security-and-access-control/auth/basic-auth)** to allow front-end requests:
```http
PUT /Client/basic?_pretty=true
content-type: application/json
accept: application/json

{
 "secret": "secret",
 "grant_types": [
  "basic"
 ]
}

Define an Access Policy to permit basic authentication: ```http PUT /AccessPolicy/basic-policy?_pretty=true content-type: application/json accept: application/json

{ “engine”: “allow”, “link”: [ { “id”: “basic”, “resourceType”: “Client” } ] }

Now we can use Basic Authorization header in the front-end:

“Authorization”: “Basic YmFzaWM6c2VjcmV0”

We use it in `src/constants.ts` file.

## Running the application
1. Install dependencies:
```bash
npm install

Start the development server:
```
npm run dev
```
Go to http://localhost:3000.

To save Patient and DocumentReference resources and the photo in the bucket:

Fill the patient form,
Attach the patient photo,
Press submit button. To get Patient photo by the id, type the id and press Get Photo button.

What’s going on under the hood?

Saving a File to the Bucket: Workflow

Send a POST request from the front-end to Aidbox with the desired filename: ```http POST /aws/storage//

filename: patient.png

2. Receive a [pre-signed URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) from Aidbox.

AWS:
```json
{
  "url": "https://<your-bucket-name>.s3.amazonaws.com/patient.png?..."
}

MinIO:

{
  "url": "http://127.0.0.1:9000/mybucket/John_Smith_20250226.png?..."
}

Upload the file directly to S3 by sending a POST request to the pre-signed URL. The file content (e.g., the patient’s photo) is sent in the request body and saved in the bucket.

Retrieving a File from the Bucket: Workflow

Send a GET request from the front-end to Aidbox with the filename:

GET /aws/storage/<your-account-id-in-aidbox>/<your-bucket-name>/<filename>

Receive a presigned URL from Aidbox.

AWS:

{
  "url": "https://<your-bucket-name>.s3.amazonaws.com/patient.png?..."
}

MinIO:

{
  "url": "http://127.0.0.1:9000/mybucket/John_Smith_20250226.png?..."
}

Use GET request to the URL to retrieve the file. For images, an HTML tag can be used to render the image directly:
```
<img
  src="<signed-url>"
/>
```

FHIR & binary files

In this example, the Attachment FHIR datatype is used to store the file’s URL. Specifically, the Patient.photo field contains an attachment representing the saved photo.

Example: Patient Resource

{
  "name": [
    {
      "given": [
        "John"
      ],
      "family": "Smith"
    }
  ],
  "photo": [
    {
      "url": "http://127.0.0.1:9000/mybucket/John_Smith_20250226.png",
      "title": "John_Smith_20250226.png",
      "contentType": "image/png"
    }
  ],
  "birthDate": "2025-02-26",
  "resourceType": "Patient",
  "id": "8f886cb7-fab3-448b-977c-0b7226b9fe9f",
  "meta": {
    "lastUpdated": "2025-02-26T13:50:59.295229Z",
    "versionId": "38",
    "extension": [
      {
        "url": "ex:createdAt",
        "valueInstant": "2025-02-26T13:50:59.295229Z"
      }
    ]
  }
}

Additionally, a DocumentReference resource can be created to store metadata about the image. See DocumentReference’s scope and usagee.

Example: DocumentReference Resource

{
  "status": "current",
  "content": [
    {
      "attachment": {
        "url": "http://127.0.0.1:9000/mybucket/John_Smith_20250226.png",
        "title": "John_Smith_20250226.png",
        "contentType": "image/png"
      }
    }
  ],
  "resourceType": "DocumentReference",
  "id": "5e390018-2f27-49a4-839a-4b0e10391bf1",
  "meta": {
    "lastUpdated": "2025-02-26T13:50:59.277060Z",
    "versionId": "37",
    "extension": [
      {
        "url": "ex:createdAt",
        "valueInstant": "2025-02-26T13:50:59.277060Z"
      }
    ]
  }
}

This site is open source. Improve this page.