Open Source Reference Service

Reference service for managing users, products, business capabilities, and technical capabilities. Built on Spring Boot 2.7.3 using PostgreSQL as the database.

Description

Open Source Reference Service is a REST API service that provides functionality for managing reference data in enterprise architecture. The service supports management of:

• Users - user creation and password management
• Products - product management with Structurizr integration
• Business Capabilities - business capability management with hierarchy support
• Technical Capabilities - technical capability management and their relationships

Technology Stack

• Java 17
• Spring Boot 2.7.3
• PostgreSQL 15
• Flyway - database migrations
• Spring Data JPA - database operations
• Swagger/OpenAPI - API documentation
• Maven - build system

Requirements

• Docker and Docker Compose
• Or Java 17+ and Maven 3.8+ for local development

Quick Start with Docker Compose

The easiest way to run the project is using Docker Compose:

# Clone the repository
git clone <repository-url>
cd opensource-reference-service

# Start services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f app

After startup, the service will be available at:

• API: http://localhost:8080
• Swagger UI: http://localhost:8080/swagger-ui/index.html (available without authentication)
• Swagger API Docs: http://localhost:8080/v2/api-docs
• Actuator: http://localhost:8080/actuator
• Prometheus Metrics: http://localhost:8080/actuator/prometheus

Note: Swagger UI is configured and available without authentication for convenient API development and testing.

PostgreSQL will be available on port 5432:

• Host: localhost
• Port: 5432
• Database: reference_service
• Username: postgres
• Password: postgres

Security and Authentication

Default User

On first installation, an administrator user is automatically created with the following credentials:

• Login: admin
• Password: admin

⚠️ IMPORTANT: It is strongly recommended to immediately change the administrator password after the first installation of the service!

Changing Administrator Password

After starting the service, execute the following request to change the administrator password:

# Get admin user ID (need to authenticate as admin)
curl -X GET http://localhost:8080/api/v1/users \
  -u admin:admin \
  -H "Content-Type: application/json"

# Change password (admin user ID is usually 1)
curl -X PATCH http://localhost:8080/api/v1/users/1/password \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{"password": "new_secure_password"}'

Or use Swagger UI to perform these operations: http://localhost:8080/swagger-ui/index.html

Basic Authentication

The service supports HTTP Basic Authentication for all protected endpoints (except Swagger UI and Actuator).

Using Basic Authentication

In curl:

curl -X GET http://localhost:8080/api/v1/product \
  -u username:password \
  -H "Content-Type: application/json"

In HTTP requests: The Authorization header must contain Basic <base64(login:password)>:

Authorization: Basic YWRtaW46YWRtaW4=

Where YWRtaW46YWRtaW4= is the base64-encoded string admin:admin.

Example header generation:

# Linux/Mac
echo -n "admin:admin" | base64

# Or in Python
python3 -c "import base64; print(base64.b64encode(b'admin:admin').decode())"

In Postman/Insomnia:

1. Select authentication type "Basic Auth"
2. Enter login and password
3. The tool will automatically add the Authorization header

User Management

Creating a New User

Only administrators can create new users:

curl -X POST http://localhost:8080/api/v1/users \
  -u admin:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "login": "new_user",
    "admin": false
  }'

Parameters:

• login - user login (Latin letters and numbers only, no spaces, up to 255 characters)
• admin - administrator flag (true/false)

⚠️ Important: When creating a user, the password is automatically set equal to the login. The new user must change the password after first login via the PATCH /api/v1/users/{id}/password endpoint.

Changing Own Password

Any user can change their own password:

curl -X PATCH http://localhost:8080/api/v1/users/{id}/password \
  -u your_login:your_current_password \
  -H "Content-Type: application/json" \
  -d '{"password": "new_password"}'

Password Requirements:

• Must not be empty
• Maximum 255 characters
• Must not contain spaces
• Must contain only ASCII characters (Latin letters, numbers, special characters)

Access Rights

• GET requests: Available to all authenticated users
• POST/PUT/PATCH requests: Require administrator rights
• Exception: Users can change their own password via PATCH /api/v1/users/{id}/password

Security Recommendations

1. Change the administrator password immediately after installation
2. Use strong passwords for all users
3. Limit the number of administrators - create administrators only when necessary
4. Use HTTPS in production environment
5. Regularly review the list of users and their access rights
6. Do not use default passwords in production

Local Development

Database Setup

1. Install PostgreSQL 15+
2. Create a database:

CREATE DATABASE reference_service;

3. Configure environment variables or create application-local.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/reference_service
spring.datasource.username=postgres
spring.datasource.password=postgres

Build and Run

# Build the project
mvn clean package

# Run the application
java -jar target/opensource-reference-service-0.0.11.jar

API Endpoints

Users

• POST /api/v1/users - Create user (requires administrator rights)
• PATCH /api/v1/users/{id}/password - Change user password (user can only change their own password)

Note: All API endpoints (except Swagger UI and Actuator) require Basic authentication.

Products

• GET /api/v1/product - Get all products
• PUT /api/v1/product/{alias} - Create/update product

Business Capabilities

• GET /api/v1/business-capability - Get business capabilities (with pagination support)
• PUT /api/v1/business-capability - Create/update business capability

Technical Capabilities

• GET /api/v1/tech-capability - Get technical capabilities (with pagination support)
• PUT /api/v1/tech-capability - Create/update technical capability

System

• GET / - Application version information
• GET /actuator/health - Application health check
• GET /actuator/metrics - Application metrics
• GET /actuator/prometheus - Prometheus metrics

Database Structure

The project uses Flyway for database migration management. Migrations are located in src/main/resources/db/migration/:

• V0001__create_schema_users.sql - Create users schema
• V0002__create_table_user.sql - Create user table
• V0003__create_capability_schema.sql - Create capability schema
• V0004__create_business_capability_table.sql - Create business capability table
• V0005__create_products_schema_and_table.sql - Create products schema and table
• V0006__create_table_tech_capability.sql - Create technical capability table
• V0007__create_capability_tech_capability_relations_table.sql - Create relations table
• V008__add_column_to_product_table.sql - Add columns to product table

Configuration

Main application settings are in application.properties. For Docker environment, environment variables are used:

• SPRING_DATASOURCE_URL - Database connection URL
• SPRING_DATASOURCE_USERNAME - Database username
• SPRING_DATASOURCE_PASSWORD - Database password
• APP_ROUTES_DASHBOARD - Dashboard URL
• APP_ROUTES_ARCHITECTURE_CENTER - Architecture center URL
• APP_ROUTES_STRUCTURIZR_BACKEND - Structurizr backend URL

Routing / Proxy (app.routes.*)

This service contains a simple reverse-proxy routing mechanism implemented as a servlet filter (RoutingFilter). It allows you to forward requests to other services based on the first path segment of the URL.

How it works

• Routes are defined in application configuration (app.routes.*)
• Each route name is mapped to a target host (base URL)
• When a request comes in, the path is split by /
• The first segment of the path (e.g. users in /users/profile) is treated as a route prefix
• If this prefix exists in app.routes, the request is proxied to the mapped host:
  • Target URL: {ROUTE_HOST}/{original path without the first segment}
  • HTTP method, request parameters, headers and body are preserved
• Authentication and authorization are checked before routing (according to the current AuthFilter logic)
• The response from the target service (status, headers, body) is returned to the client unchanged
• If the path does not start with any configured route prefix, the service processes the request with its own controllers as usual (and returns 404 if there is no handler)

Configuration

Define routes in application.properties:

app.routes.users=http://user-service:8080
app.routes.products=http://product-service:8081

Or via environment variables (Spring Boot relaxed binding):

APP_ROUTES_USERS=http://user-service:8080
APP_ROUTES_PRODUCTS=http://product-service:8081

Examples

• Request GET /users/profile will be proxied to http://user-service:8080/profile
• Request POST /products/create will be proxied to http://product-service:8081/create
• Request GET {opensource-reference-service-host}/dashboard/api/v1/capability:
  • First path segment is dashboard
  • If there is a route app.routes.dashboard=https://beeline.com, the request will be proxied to https://beeline.com/api/v1/capability
  • If there is no such route, the service will try to handle GET /dashboard/api/v1/capability itself; if no handler exists, it will return 404

Authentication

The authentication filter runs before routing. This means proxied requests still require the same authentication headers as any other protected endpoint, and the proxy will forward these headers to the target service.

Docker

Building Image

docker build -t opensource-reference-service:latest .

Running Container

docker run -d \
  -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/reference_service \
  -e SPRING_DATASOURCE_USERNAME=postgres \
  -e SPRING_DATASOURCE_PASSWORD=postgres \
  opensource-reference-service:latest

Monitoring

The application provides metrics through Spring Boot Actuator and Prometheus:

• Health checks: /actuator/health
• Metrics: /actuator/metrics
• Prometheus endpoint: /actuator/prometheus

Development

Project Structure

src/main/java/ru/beeline/referenceservice/
├── config/          # Configuration classes
├── controller/      # REST controllers
├── domain/          # JPA entities
├── dto/             # Data Transfer Objects
├── exception/       # Exceptions
├── filter/          # HTTP filters
├── mapper/          # Data transformation mappers
├── repository/      # JPA repositories
├── service/         # Business logic
└── util/            # Utilities

Running Tests

mvn test

License

See the LICENSE.txt file for detailed license information.

Copyright

Copyright (c) 2024 PJSC VimpelCom

Contacts

For questions and suggestions, please create an issue in the project repository.