OEPS Client

A read-only Rust client for the Onroerend Erfgoed API with Link header-based pagination and comprehensive filtering.

Warning

This crate is the result of an ongoing experiment in vibe coding using Mistral Vibe. While >it is functional, it is not stable or actively maintained. The goal of the project was to learn about coding with LLM tools and to assess the quality and the developer experience (I am a LLM skeptic). I will report on my experiences in the Wiki, but if I decide to create an actual project, I will likely reimplement from scratch without LLM's.

Crates Overview

The OEPS client consists of three main crates:

• oeps_client: Main client library with pagination, filtering, and configuration support
• oeps_models: Manually maintained data models providing type-safe API interactions
• oeps_cli: Command-line interface for API interactions with comprehensive filtering

Installation

Client Library

Add to your Cargo.toml:

[dependencies]
oeps_client = { git = "https://codeberg.org/maarten-vermeyen/oeps.git" }

Data Models Only

[dependencies]
oeps_models = { git = "https://codeberg.org/maarten-vermeyen/oeps.git" }

CLI Installation

git clone "https://codeberg.org/maarten-vermeyen/oeps.git"
cd oeps
cargo install --path crates/oeps_cli

Installation

Choose the crate that fits your needs:

Full Client Library

[dependencies]
oeps_client = { git = "https://codeberg.org/maarten-vermeyen/oeps.git", package = "oeps_client"}

Data Models Only

[dependencies]
oeps_models = { git = "https://codeberg.org/maarten-vermeyen/oeps.git" }

CLI

To install the command line client:

• check out the workspace
• run cargo install

git clone "https://codeberg.org/maarten-vermeyen/oeps.git"
cd oeps
cargo install --path crates/oeps_cli

Basic Usage

Client Library Example

use oeps_client::ApiClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client with default configuration
    let client = ApiClient::new();
    
    // Make a simple GET request
    let request = oeps_client::models::requests::ApiRequest::get("/aanduidingsobjecten")
        .with_query_param("limit", "10")
        .build();
    
    let response = client.execute::<serde_json::Value>(request).await?;
    println!("Response: {:?}", response);
    
    Ok(())
}

CLI Examples

# Basic list command
oeps aanduidingsobjecten list

# List with filtering
oeps erfgoedobjecten list --gemeente "Antwerpen"

# List with full details
oeps aanduidingsobjecten list --full

# List all pages automatically, this is rate linited, 
# so will take a some time for large datasets. It will
# take very long when combined with --full for medium 
# to large result sets.
oeps gebeurtenissen list --gemeente Malle

# Get single object
oeps aanduidingsobjecten get 12345

Architecture

The client follows a modular architecture with clear separation of concerns across multiple crates:

Workspace Structure

crates/
├── oeps_models/                 # Manually maintained data models
├── oeps_client/            # Main client library with pagination and filtering
└── oeps_cli/               # Command-line interface

Key Components

• oeps_models: Manually maintained data models providing type-safe API interactions
• oeps_client: Main API client with request/response handling and pagination support
• oeps_cli: User-friendly command-line tool for API interactions

Choose the level of abstraction you need:

1. CLI Users: oeps_cli for ready-to-use command-line tool
2. Library Users: oeps_client for programmatic access with full features
3. Data-Only Users: oeps_models crate for just the type definitions

See ARCHITECTURE.md for more details.

Development

Workspace Structure

# Build all crates
cargo build --workspace

# Build specific crate
cargo build -p oeps_client
cargo build -p oeps_models
cargo build -p oeps_cli

Prerequisites

• Rust 1.60+
• Cargo
• Docker (for OpenAPI generation)

Testing

cargo test

Data Models

The project uses manually maintained data models:

• Manual Maintenance: Types are maintained manually for better control
• Comprehensive Coverage: Full API coverage with Rust type safety
• Custom Enhancements: Types can be customized for specific use cases

Model Structure

crates/oeps_models/
├── src/
│   ├── models/
│   │   ├── common/       # Shared components (Locatie, Systemfields, Kenmerkgroep, etc.)
│   │   ├── entities/     # Main entity types (Aanduidingsobject, Erfgoedobject, Gebeurtenis, etc.)
│   │   ├── dates/        # Date and time types (Periode, Datum, etc.)
│   │   ├── geography/    # Geographic types (polygons, location elements, etc.)
│   │   ├── identifiers/  # Identifier types (NumberString, IntegerString)
│   │   ├── media/        # Media and attachment types (Bijlagen)
│   │   ├── relationships/# Relationship models (Relaties)
│   │   ├── status/       # Status enums (ObjectStatus, FysiekeStatus)
│   │   ├── text/         # Text-related types (TekstDatumGranulariteit, etc.)
│   │   ├── themas/       # Thema-related types
│   │   ├── errors/       # Error types (Error, ValidationError)
│   │   ├── traits/       # Common traits (WalkFields, VisitFields)
│   │   └── mod.rs        # Module exports
│   └── lib.rs            # Crate root exports
├── Cargo.toml            # Dependencies
└── README.md             # Model documentation

The models crate contains 100+ data models organized into logical domain modules. All modules are re-exported at the crate root for a clean interface:

// Clean import paths - use module domains directly from crate root
use oeps_models::common::Locatie;
use oeps_models::entities::Aanduidingsobject;
use oeps_models::status::{ObjectStatus, FysiekeStatus};
use oeps_models::text::TekstDatumGranulariteit;
use oeps_models::traits::{VisitFields, WalkFields};

Adding New Models

When the API changes or new endpoints are needed:

1. Review the API documentation
2. Update existing models or add new ones manually
3. Follow the existing patterns in crates/oeps_models/src/models/
4. Add proper documentation and examples
5. Test with real API calls

Using Models in Your Code

The clean interface allows direct imports from the crate root:

// Import types from their domain modules
use oeps_models::common::Locatie;
use oeps_models::entities::Aanduidingsobject;
use oeps_models::geography::LocatieElementenInner;
use oeps_models::status::ObjectStatus;

// Or import the entire module
use oeps_models::entities;
use oeps_models::traits::VisitFields;

Model Enhancements

The models can be enhanced with:

• Custom serialization/deserialization
• Builder patterns for complex types
• Validation methods
• Helper functions for common operations

Documentation

• Architecture Overview
• ROADMAP
• API Documentation

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

🚧 Planned Features

See ROADMAP.md for detailed roadmap and prioritization.

Support

For issues and questions, please open a issue on Codeberg.org.

Acknowledgments

• Onroerend Erfgoed for providing the API