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
- Logical operators
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.