iDempiere REST API

Overview

• What you’ll learn:
  • How to enable and configure iDempiere’s RESTful API for external system integrations
  • How to perform CRUD operations and use query parameters for filtering, sorting, pagination, and field selection
  • How to handle authentication, error responses, batch operations, and security considerations when building API integrations
• Prerequisites: Lesson 2 — iDempiere Architecture Overview, Lesson 3 — Installing iDempiere (running instance required)
• Estimated reading time: 22 minutes

Introduction

Modern enterprise systems rarely operate in isolation. Organizations need their ERP to communicate with e-commerce platforms, mobile applications, business intelligence tools, and third-party services. iDempiere addresses this need through a comprehensive RESTful API that exposes business data and operations over standard HTTP, enabling external systems to create, read, update, and delete records without direct database access.

The iDempiere REST API follows OData-inspired conventions, providing a consistent and predictable interface for interacting with any table and window defined in the Application Dictionary. In this lesson, you will learn how to enable the API, authenticate your requests, perform CRUD operations, and leverage query parameters for powerful data retrieval. Every concept is demonstrated with practical curl commands you can execute against your own iDempiere instance.

REST API Overview and Setup

The iDempiere REST API is provided by the org.idempiere.rest plugin bundle, which ships with iDempiere but may need to be explicitly enabled depending on your installation. The API exposes iDempiere’s Application Dictionary-defined windows and tables as RESTful resources.

Enabling the REST API

In most modern iDempiere installations (version 10 and later), the REST API plugin is included by default. To verify it is active:

1. Log in to iDempiere as System Administrator.
2. Navigate to the OSGi console or check the bundle status using the Felix web console (typically at http://localhost:8080/osgi/system/console/bundles).
3. Search for org.idempiere.rest bundles — ensure they are in the Active state.

If the bundles are not active, you can start them from the OSGi console or add them to your server configuration.

API Base URL and Versioning

The REST API is accessible at a base URL following this pattern:

http://<host>:<port>/api/v1/

For a local development installation, this is typically:

http://localhost:8080/api/v1/

The v1 segment represents the API version. As the API evolves, new versions may be introduced while maintaining backward compatibility with existing versions. Always include the version prefix in your API calls to ensure consistent behavior across iDempiere upgrades.

Authentication Methods

Every API request must be authenticated. iDempiere’s REST API supports token-based authentication as its primary mechanism.

Token-Based Authentication

The recommended approach is to obtain an authentication token by sending credentials to the auth endpoint, then including that token in subsequent requests:

# Step 1: Obtain a token
curl -X PUT \
  http://localhost:8080/api/v1/auth/tokens \
  -H 'Content-Type: application/json' \
  -d '{
    "userName": "GardenAdmin",
    "password": "GardenAdmin"
  }'

A successful response returns a JSON object containing the token and context selection options:

{
  "clients": [
    {
      "id": 11,
      "name": "GardenWorld",
      "roles": [
        {
          "id": 102,
          "name": "GardenWorld Admin",
          "organizations": [
            { "id": 0, "name": "*" },
            { "id": 11, "name": "HQ" }
          ],
          "warehouses": [
            { "id": 103, "name": "HQ Warehouse" }
          ]
        }
      ]
    }
  ],
  "token": "eyJhbGciOiJIUzUxMiJ9..."
}

Setting the Context

After obtaining a token, you must set the working context (client, role, organization, warehouse) — the same context you select when logging in through the web UI:

# Step 2: Set context using the token
curl -X PUT \
  http://localhost:8080/api/v1/auth/tokens \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...' \
  -d '{
    "clientId": 11,
    "roleId": 102,
    "organizationId": 11,
    "warehouseId": 103,
    "language": "en_US"
  }'

Using the Token in Requests

Include the token in every subsequent API request using the Authorization header:

curl -X GET \
  http://localhost:8080/api/v1/windows/business-partner \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

CRUD Operations

The REST API maps standard HTTP methods to CRUD operations on iDempiere records. Resources are accessed through window slugs (URL-friendly names derived from window names in the Application Dictionary).

GET — Retrieve Records

Use GET requests to retrieve single records or lists of records.

Retrieve a List of Records

# Get all business partners
curl -X GET \
  http://localhost:8080/api/v1/windows/business-partner \
  -H 'Authorization: Bearer <token>'

The response includes a JSON array of records with their fields:

{
  "page-count": 5,
  "records-size": 50,
  "skip-records": 0,
  "row-count": 234,
  "array-count": 50,
  "records": [
    {
      "id": 118,
      "uid": "abc12345-...",
      "Value": "JoeBlock",
      "Name": "Joe Block",
      "IsCustomer": true,
      "IsVendor": false,
      ...
    },
    ...
  ]
}

Retrieve a Single Record

# Get business partner with ID 118
curl -X GET \
  http://localhost:8080/api/v1/windows/business-partner/118 \
  -H 'Authorization: Bearer <token>'

POST — Create Records

Use POST requests to create new records. The request body contains the field values as a JSON object:

# Create a new business partner
curl -X POST \
  http://localhost:8080/api/v1/windows/business-partner \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Value": "NEWCUST001",
    "Name": "New Customer Inc.",
    "IsCustomer": true,
    "IsVendor": false,
    "C_BP_Group_ID": 104
  }'

A successful creation returns HTTP status 201 Created with the complete record, including system-generated fields like id, Created, and CreatedBy.

PUT — Update Records

Use PUT requests to update existing records. Include only the fields you want to modify:

# Update business partner name
curl -X PUT \
  http://localhost:8080/api/v1/windows/business-partner/118 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Name": "Joe Block International"
  }'

The API returns HTTP status 200 OK with the updated record.

DELETE — Remove Records

Use DELETE requests to deactivate or remove records:

# Delete a business partner record
curl -X DELETE \
  http://localhost:8080/api/v1/windows/business-partner/118 \
  -H 'Authorization: Bearer <token>'

Note that in iDempiere, deletion may be restricted by business rules. Referenced records (for example, a business partner with existing orders) cannot be deleted. The API will return an appropriate error message in such cases.

Query Parameters for Filtering and Retrieval

The REST API supports OData-style query parameters that give you fine-grained control over which records are returned and how they are presented.

Filtering with $filter

Use the $filter parameter to apply conditions to your queries:

# Get only customers (not vendors)
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$filter=IsCustomer eq true' \
  -H 'Authorization: Bearer <token>'

# Filter by name containing a string
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$filter=Name contains Joe' \
  -H 'Authorization: Bearer <token>'

# Combine multiple conditions
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$filter=IsCustomer eq true and IsActive eq true' \
  -H 'Authorization: Bearer <token>'

Supported filter operators include: eq (equal), neq (not equal), gt (greater than), lt (less than), ge (greater than or equal), le (less than or equal), contains, startswith, endswith, and, or.

Sorting with $orderby

Control the order of results using the $orderby parameter:

# Sort by name ascending
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$orderby=Name asc' \
  -H 'Authorization: Bearer <token>'

# Sort by creation date descending
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$orderby=Created desc' \
  -H 'Authorization: Bearer <token>'

Pagination with $top and $skip

For large datasets, use pagination parameters to retrieve records in manageable pages:

# Get the first 10 records
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$top=10' \
  -H 'Authorization: Bearer <token>'

# Skip the first 20 records and get the next 10 (page 3)
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$top=10&$skip=20' \
  -H 'Authorization: Bearer <token>'

Field Selection with $select

Reduce response payload size by requesting only specific fields:

# Get only ID, Value, and Name fields
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$select=Value,Name' \
  -H 'Authorization: Bearer <token>'

Expanding Related Records with $expand

The $expand parameter retrieves child tab records in a single request, avoiding the need for multiple API calls:

# Get a sales order with its order lines
curl -X GET \
  'http://localhost:8080/api/v1/windows/sales-order/104?$expand=order-line' \
  -H 'Authorization: Bearer <token>'

The expanded records appear as a nested array within the parent record’s JSON response.

Combining Query Parameters

All query parameters can be combined for precise data retrieval:

# Active customers, sorted by name, page 2 (10 per page), limited fields
curl -X GET \
  'http://localhost:8080/api/v1/windows/business-partner?$filter=IsCustomer eq true and IsActive eq true&$orderby=Name asc&$top=10&$skip=10&$select=Value,Name,TotalOpenBalance' \
  -H 'Authorization: Bearer <token>'

Working with Detail Tabs

iDempiere windows often have parent-child relationships expressed as header and detail tabs. The API represents these as nested resources:

# Get order lines for a specific sales order
curl -X GET \
  http://localhost:8080/api/v1/windows/sales-order/104/order-line \
  -H 'Authorization: Bearer <token>'

# Create a new order line on an existing order
curl -X POST \
  http://localhost:8080/api/v1/windows/sales-order/104/order-line \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "M_Product_ID": 134,
    "QtyOrdered": 10,
    "PriceEntered": 25.00
  }'

Process Execution via API

Beyond CRUD operations, the API allows you to invoke iDempiere processes, such as document completion:

# Run a process (e.g., complete a document)
curl -X PUT \
  http://localhost:8080/api/v1/windows/sales-order/104/doc-action \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "DocAction": "CO"
  }'

Common document actions include: CO (Complete), CL (Close), VO (Void), RE (Reverse Correct), PR (Prepare).

Error Responses and Status Codes

The REST API uses standard HTTP status codes to indicate the result of operations:

Error responses include a JSON body with details about the failure:

{
  "title": "Save error",
  "status": 500,
  "detail": "Cannot delete record because it is referenced by other records."
}

Security Considerations

Exposing an API adds an attack surface to your iDempiere installation. Follow these best practices to secure your deployment.

CORS Configuration

Cross-Origin Resource Sharing (CORS) controls which domains can make API requests from a browser. Configure CORS to allow only trusted origins:

• In production, restrict allowed origins to specific domains rather than using a wildcard (*).
• Configure CORS headers in your reverse proxy (Apache or Nginx) or in the iDempiere REST plugin settings.

API Token Security

• Never embed tokens in client-side JavaScript or mobile app source code.
• Store tokens securely and transmit them only over HTTPS.
• Implement token rotation — periodically re-authenticate to obtain fresh tokens.
• Use roles with minimum required permissions for API access. Create dedicated API roles that grant access only to the specific windows and records needed by the integration.

Rate Limiting

While iDempiere does not include built-in rate limiting, you should implement it at the infrastructure level using your reverse proxy:

# Nginx rate limiting example
limit_req_zone $binary_remote_addr zone=api:10m rate=100r/m;

location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://localhost:8080;
}

HTTPS

Always use HTTPS in production to encrypt API traffic. Configure SSL/TLS termination at your reverse proxy or load balancer. Never transmit authentication tokens over unencrypted HTTP connections.

Common Integration Patterns

Here are several practical patterns for integrating external systems with iDempiere through the REST API.

E-Commerce Order Sync

Synchronize orders from an online store into iDempiere:

1. Authenticate and obtain a token.
2. Look up or create the business partner using a GET with $filter, then POST if not found.
3. Create a sales order header via POST to /windows/sales-order.
4. Create order lines via POST to /windows/sales-order/{id}/order-line for each cart item.
5. Complete the order using a document action PUT.

Inventory Polling

External systems can poll iDempiere for current stock levels:

# Get product inventory (Storage on Hand)
curl -X GET \
  'http://localhost:8080/api/v1/windows/material-receipt?$filter=M_Product_ID eq 134&$select=QtyOnHand' \
  -H 'Authorization: Bearer <token>'

Reporting Data Extraction

Business intelligence tools can extract data for dashboards and reports by querying the API with specific filters and field selections, paginating through large result sets as needed.

Summary

The iDempiere REST API transforms iDempiere from a standalone ERP into an integration-ready platform. You learned how to authenticate using tokens, perform full CRUD operations, leverage query parameters for efficient data retrieval, handle errors gracefully, and secure your API deployment. In the next lesson, you will build on this foundation by creating custom REST endpoints that expose your own business logic to external systems.