REST Web Services

• Maintainers: BX Service GmbH team
• Status: used in production, up to date with release 8.2, 9 and master
• License: GPLv2
• Sources: https://github.com/bxservice/idempiere-rest
• Continuous Integration: https://jenkins.idempiere.org/job/idempiere-rest/

Common Headers

• Content-Type: application/json
• Accept: application/json
• Authorization: Bearer {authToken}
  • All calls except the first one (POST/auth) requires an authorization bearer that is returned by the /auth APIs

PO json record

PO GET

PO json records returned in a GET operation are formatted as:

• id -> the record ID
• uid -> the UUID of the record
• model-name -> the table name of the record
• {columnname} -> each pair of column/value is represented as a json object with the columnname
  • String: strings are represented directly as a json string quoted value
  • Yes/No: these are represented as true/false
  • Numbers: numbers are represented as a json number without quotes
  • Dates/Times: timestamp values are represented as a json date (quoted string with format ISO_8601
  • Foreign keys: these are represented as a json object with the following values:
    • propertyLabel -> the foreign name
    • id -> the foreign record ID
    • identifier -> the foreign identifier
    • model-name -> the foreign table name

PO POST/PUT

PO json records used to insert/update in a PUT operation:

• tableName -> the table name of the record
• {columnname} -> each pair of column/value is represented as a json object with the columnname
  • String: strings are represented directly as a json string quoted value
  • Yes/No: these are represented as true/false
  • Numbers: numbers are represented as a json number without quotes
  • Dates/Times: timestamp values are represented as a json date (quoted string with format ISO_8601
  • Foreign keys: these are represented as a json object with the following values:
    • identifier -> the foreign identifier
    • tableName -> the foreign table name

Filter operators

$filter is a common parameter in several endpoints, it can manage some operators, close to odata standard:

• $filter
  • Logical operators
    • eq -> equals =
    • neq -> not equals !=
    • gt -> greater than >
    • ge -> greater or equal >=
    • lt -> less than <
    • le -> less or equal <=
    • and -> &
    • not -> !
  • Method operators:
    • contains -> if a string contains another string
    • startswith -> if a string starts with another string
    • endswith -> if a string ends with another string
    • tolower -> convert a string to lowercase
    • toupper -> convert a string to uppercase

Resources

Authentication api/v1/auth

Authentication and jwt token

POST api/v1/auth

This must be the first call to the application, returning an access token and a list of the clients that this user/password has access to.

Body Parameters:

• userName
• password

Returns:

• clients
  • id
  • name
• token
  • this token can just be used to call the /auth endpoint

PUT api/v1/auth

Body Parameters:

• clientId
• roleId
• organizationId
• warehouseId
• language

Returns:

• userId
• language
• token
  • this token is to be used in all the other calls

GET api/v1/auth/roles

TBD

GET api/v1/auth/organizations

TBD

GET api/v1/auth/warehouses

TBD

GET api/v1/auth/language

TBD

GET api/v1/auth/jwk

TBD

Models api/v1/models

GET api/v1/models

URL Parameters:

• $filter -> used to filter the query

Returns:

• models
  • id
  • uid
  • model-name
  • name
  • description

GET api/v1/models/{tablename}

URL Parameters:

• $select -> used to define the columns that we want in the returned query
• $filter -> used to filter the query
• $orderby -> to define the columns used to order by the records
• $top -> obtain just this number of records (a value of zero means to use the default defined in SysConfig REST_MAX_RECORDS_SIZE)
• $skip -> skip this number of records, in combination with top this is used for pagination
• $expand -> to get PO records from detail tables
• $valrule -> to get PO records using a validation rule - AD_ValRule_ID or AD_ValRule_UU
• $context -> to put variables in context to be parsed by the validation rule

Returns:

• page-count: the number of pages required to get all the records based on the record size
• records-size: the maximum number of records returned per page
• skip-records: the number of records skipped at the beginning of the query
• row-count: the total number of records found
• array-count: the exact number of records returned in this call
• records
  • an array of PO json records from the table being queried

NOTE: these properties are also returned as headers in the response.

Examples:

/api/v1/models/c_elementvalue

POST api/v1/models/{tablename}

This method is used to insert a record in the database

Body Parameters:

• PO json record to insert

Returns:

• The PO json record inserted (with the new ID)

GET api/v1/models/{tablename}/{recordId}

This variation of the GET method obtains directly the record from the table with the record ID received as the URL portion

It works also with UUID instead of recordID

Returns:

• a PO json record

GET api/v1/models/{tablename}/{recordId}/{columnname}

This variation of the GET method obtains directly the value of the column from the record from the table with the record ID received as the URL portion

Returns:

• a PO json record containing JUST the column requested

PUT api/v1/models/{tablename}/{recordId}

This method is used to update a record in the database

Body Parameters:

• PO json record to update

Returns:

• The PO json record updated

DEL api/v1/models/{tablename}/{recordId}

This method is used to delete a record from the database

Returns:

• msg -> confirming the deletion

Windows api/v1/windows

working with AD_Window and AD_Tab

TBD

Forms api/v1/forms

GET api/v1/forms

Get Forms available

URL Parameters:

• $filter -> optional - used to filter the query

Returns:

• an array of PO json records from the forms (AD_Form) queried

Processses api/v1/processes

working with process and reports

TBD

Files api/v1/files

to access files created by api/v1/processes

TBD

Caches api/v1/caches

GET api/v1/caches

Get caches information

URL Parameters:

• table_name -> optional - to filter the list of caches
• name -> optional - to filter the list of caches

Returns:

• caches (array)
  • name
  • table_name
  • size
  • expireMinutes
  • maxSize
  • distributed (boolean)

DEL api/v1/caches

Reset cache

When called without parameters it reset the whole cache, or just from a table, or just one record.

URL Parameters:

• table_name -> optional - to restrict the reset to just one table
• record_id -> optional - to restrict the reset to just one record

Returns:

• entriesReset (number of entries cleared)

Nodes api/v1/nodes

get nodes info, get log files, reset and rotate logs.

TBD

Servers api/v1/servers

servers and schedulers resource

TBD

Infos api/v1/infos

info windows

TBD

Reference api/v1/reference/{id}

Get reference list by id/uuid

TBD

Workflows api/v1/workflow

GET api/v1/workflow

Returns:

• all suspended, non-processed nodes of the current user
  • id
  • uid
  • model-name
  • node-name
  • node-description
  • priority
  • summary
  • node-help
  • history-records
  • ad_table_id
  • record_id

GET api/v1/workflow/{userid}

Returns:

• all suspended, non-processed nodes of the user id passed in the URL
  • id
  • uid
  • model-name
  • node-name
  • node-description
  • priority
  • summary
  • node-help
  • history-records
  • ad_table_id
  • record_id

Examples:

/api/v1/models/101

PUT api/v1/workflow/approve/{nodeid}

Approves the corresponding node. Just for nodes of type = Approval (Column name = IsApproved).

Body Parameters:

• "message": "This is an example message for approval" (Optional)

Returns:

• Confirmation of the approval

PUT api/v1/workflow/reject/{nodeid}

Rejects the corresponding node. Just for nodes of type = Approval (Column name = IsApproved).

Body Parameters:

• "message": "This is an example message for rejection" (Optional)

Returns:

• Confirmation of the rejection

PUT api/v1/workflow/forward/{nodeid}

Forwards the corresponding node to a specific user. Just for nodes of type = Approval (Column name = IsApproved).

Body Parameters:

• "userTo": {userToID} (Mandatory)
• "message": "This is an example message for fowarding" (Optional)

Returns:

• Confirmation of the forwarding

PUT api/v1/workflow/acknowledge/{nodeid}

Implementation of the workflow nodes where a user gets notified when something happens, it does not require any action from the user but the user receives a message after a specific action is performed. This is used when the node is from type Window/form

Body Parameters:

• "message": "This is an example message for acknowledge" (Optional)

Returns:

• Confirmation of the acknowledge

PUT api/v1/workflow/setuserchoice/{nodeid}

This is similar to approve and reject but it supports columns with Type List and String.

Body Parameters:

• "value":"Value to be set in the corresponding column" (Mandatory)
• "message": "This is an example message for userschoice" (Optional)

Returns:

• Confirmation of the acknowledge

SysConfig Keys

IDEMPIERE_REST_EXPOSE_JWK

Y/N - defaults to N

For integration with krakend (see Proxy iDempiere-Rest Through KrakenD) it is necessary to expose the signing key in the endpoint api/v1/auth/jwk

Setting this to N (the default) the endpoint is not exposed, changing to Y it will expose the endpoint.

REST_COLUMNNAME_TOLOWERCASE

Y/N - defaults to N

When set to Y the columnnames are translated to be named as json properties. The first letter is changed to lowercase when the columnname doesn't contain the underline character ( _ )

When set to N (the default) the columnname is unchanged

REST_MAX_RECORDS_SIZE

Numeric, default 100

Max number of records returned in a get operation.

After changing this SysConfig key a server restart is required.

Note that $top cannot be higher than this configured value.

Also, REST_MAX_RECORDS_SIZE=0 means unlimited, and in this case the $top takes precedence when defined.