Fragments API

fragments-api is an authenticated Node.js and Express backend for storing, retrieving, converting, updating, and deleting content fragments. It supports local development workflows as well as AWS-backed deployment with Cognito, S3, and DynamoDB.

Features

• Authenticated REST API with Amazon Cognito in production and Basic Auth for local development
• Fragment storage with separate metadata and raw payload handling
• Support for text, Markdown, HTML, JSON, and common image formats
• On-demand content conversion through typed fragment URLs
• Swappable persistence layer with in-memory storage locally and AWS services in deployed environments
• Automated linting, testing, containerization, and deployment workflows

Supported Content Types

Source Type	Available Formats
text/plain	text/plain
text/markdown	text/markdown, text/html, text/plain
text/html	text/html, text/plain
application/json	application/json, text/plain
image/png	image/png, image/jpeg, image/webp, image/gif
image/jpeg	image/jpeg, image/png, image/webp, image/gif
image/webp	image/webp, image/png, image/jpeg, image/gif
image/gif	image/gif, image/png, image/jpeg, image/webp

API Endpoints

Method	Endpoint	Description
GET	/	Health check and service metadata
POST	/v1/fragments	Create a new fragment
GET	/v1/fragments	List fragment IDs or use ?expand=1 for metadata
GET	/v1/fragments/:id	Retrieve raw fragment data
GET	/v1/fragments/:id/info	Retrieve fragment metadata
PUT	/v1/fragments/:id	Replace fragment data without changing content type
DELETE	/v1/fragments/:id	Delete a fragment

Examples:

• GET /v1/fragments/:id.html
• GET /v1/fragments/:id.txt
• GET /v1/fragments/:id.webp

Tech Stack

• Node.js 22
• Express 5
• Passport authentication
• Amazon Cognito
• Amazon S3
• Amazon DynamoDB
• Sharp
• Jest and Supertest
• Hurl
• Docker and Docker Compose
• GitHub Actions

Local Development

Prerequisites

• Node.js 22.x
• npm 10.x
• Docker Desktop for containerized integration testing

Setup

git clone https://github.com/KenchoLodhen1/fragments-api.git
cd fragments-api
npm install

Create a .env file for your local environment. Typical local development uses:

HTPASSWD_FILE=tests/.htpasswd
PORT=8080
API_URL=http://localhost:8080
LOG_LEVEL=debug

Start the API:

npm run dev

The service runs at http://localhost:8080.

Docker

Build and run the service locally:

docker build -t fragments-api .
docker run --rm -p 8080:8080 --env-file .env fragments-api

For local AWS-compatible infrastructure, docker-compose.yml provisions:

• the API service
• LocalStack for S3
• DynamoDB Local for metadata storage

Scripts

Command	Description
npm run dev	Start the API with auto-reload and debug logging
npm start	Start the API normally
npm test	Run the Jest test suite
npm run coverage	Generate test coverage output
npm run test:integration:setup	Provision LocalStack and DynamoDB Local resources
npm run test:integration	Run Hurl integration tests
npm run test:integration:local	Reset Docker services, provision local AWS resources, and run integration tests
npm run docker:reset	Rebuild the local Docker integration environment
npm run lint	Run ESLint on source and test files

Architecture

• src/routes/ contains the Express routing layer
• src/model/fragment.js defines fragment validation, metadata, and conversion behavior
• src/model/data/memory/ provides in-memory persistence for local workflows
• src/model/data/aws/ stores metadata in DynamoDB and fragment data in S3
• src/authorization/ handles Cognito bearer-token auth and local Basic Auth

Delivery Workflow

GitHub Actions workflows handle:

• ESLint validation
• Dockerfile linting
• unit tests
• Docker image publishing

Deployment

Production deployment is designed around:

• Amazon Cognito for authentication
• Amazon S3 for fragment payload storage
• Amazon DynamoDB for fragment metadata
• Amazon ECS/Fargate for container orchestration

The repository includes an ECS task definition file from the original deployment setup.