Integrating REST API with iDempiere 12: A Comprehensive Installation Guide

Modern ERP systems require seamless integration capabilities. While iDempiere is a powerhouse of business logic, adding a robust RESTful layer unlocks its potential for mobile apps, external web services, and modern front-end frameworks.

In this guide, we will walk through the installation and configuration of the bxservice/idempiere-rest plugin specifically for iDempiere 12.

Why Use This REST API?

This specific implementation offers a comprehensive RESTful interface that goes beyond basic data entry. Key features include:

• Security: JWT Token authentication and OIDC (Keycloak/Amazon Cognito) support.
• Versatility: Full CRUD operations, Process/Report execution, and Info Window queries.
• Efficiency: REST View abstraction layer for complex data retrieval.
• Documentation: Automatic OpenAPI 3.0 (Swagger) specification generation.

Environment Prerequisites
Before we begin, ensure your environment meets the following requirements:

Step-by-Step Installation

1. Clone the Source Code
   Navigate to your source directory and pull the repository:

cd /your/source/path
git clone https://github.com/bxservice/idempiere-rest.git
cd idempiere-rest

2. Switch to a Compatible Version
   To ensure compatibility with iDempiere 12.0.0, we recommend checking out a specific stable commit that handles the transition of certain API methods (like SQLFragment).

# Using commit f141536 (Feb 2025) which includes iDempiere 12 compatibility
git checkout f141536

3. Patching Compatibility Issues
   The current iDempiere 12 release has a slight difference in the MTask class. You need to modify the TaskResourceImpl.java file to prevent build errors.

File Path: com.trekglobal.idempiere.rest.api/src/com/trekglobal/idempiere/rest/api/v1/resource/impl/TaskResourceImpl.java

Modify Lines 167-170: Replace the complex task execution block with a simple execution call:

// Simplified for iDempiere 12 compatibility
String result = task.execute();

JsonObject json = new JsonObject();
json.addProperty("result", result);

4. Configure the Parent POM
   Edit com.trekglobal.idempiere.extensions.parent/pom.xml to point to your local iDempiere P2 repository. This allows Maven to find the necessary iDempiere core dependencies.

XML

<idempiere.core.repository.url>file:///${basedir}/../../idempiere-12pt/org.idempiere.p2/target/repository</idempiere.core.repository.url>

5. Build the Plugin
   Run the Maven build process to generate the OSGi bundle:

Bash

mvn verify

The resulting JAR file will be located in the com.trekglobal.idempiere.extensions.p2/target/repository/plugins/ directory.

6. Deployment to iDempiere
   Copy the generated JAR to your iDempiere server’s plugin folder and register it in bundles.info.

Registering the Bundle: Add the following line to

.../configuration/org.eclipse.equinox.simpleconfigurator/bundles.info: com.trekglobal.idempiere.rest.api,[VERSION],plugins/com.trekglobal.idempiere.rest.api_[VERSION].jar,4,true

Database Preparation: The Slugify Function

The REST API uses a “slugify” function to convert table and column names into URL-friendly formats. Execute the following SQL in your PostgreSQL database:

SQL

CREATE EXTENSION IF NOT EXISTS "unaccent";

CREATE OR REPLACE FUNCTION slugify("value" TEXT)
RETURNS TEXT AS $$
WITH "unaccented" AS (SELECT unaccent("value") AS "value"),
"lowercase" AS (SELECT lower("value") AS "value" FROM "unaccented"),
"hyphenated" AS (SELECT regexp_replace("value", '[^a-z0-9\-_]+', '-', 'gi') AS "value" FROM "lowercase"),
"trimmed" AS (SELECT regexp_replace(regexp_replace("value", '-+$', ''), '^-', '') AS "value" FROM "hyphenated")
SELECT "value" FROM "trimmed";
$$ LANGUAGE SQL STRICT IMMUTABLE;

Quick Reference: API Endpoints

All endpoints are prefixed with /api/v1/

Usage Example: Querying Business Partners

Once installed and authenticated, you can query data using OData-style syntax:

curl -X GET "http://localhost:8080/api/v1/models/c_bpartner?$filter=IsCustomer eq true&$top=10" \
  -H "Authorization: Bearer <your_jwt_token>"

Supported Filter Operators

• eq (Equals), neq (Not Equals)
• gt / ge (Greater Than / Equal)
• like (Fuzzy Match, e.g., Name like ‘%Inc%’)
• in (Set inclusion)

Troubleshooting Tips

• Bundle not starting: Use the OSGi console (telnet localhost 12612) and run diag to check for missing dependencies (usually Jackson or Jersey libraries).
• 401 Unauthorized: Ensure you have performed the second step of authentication (the PUT request) to select your Client, Role, and Organization.
• 404 Not Found: Remember that table names in the URL must be lowercase (e.g., /models/c_order).

Reference

GitHub：bxservice / idempiere-rest
https://github.com/bxservice/idempiere-rest/blob/release-11/README.md

Taiwan’s Elite iDempiere Coding Blog
https://hackmd.io/@2GrxaqznSJKLrhmXwCaeug/SyR7qmNWgg

iDempiere REST endpoints
https://hengsin.github.io/idempiere-rest-swagger-ui/#