Types of APIs

Edit online

An API processes records based on key attribute values, processing records with a primary key first. If the primary key is not found, the API then searches for the logical keys and then processes those records. For example, the ChangeOrder() API first looks for the OrderHeaderKey key attribute and then for the combination of the OrderNo and EnterpriseCode key attributes.

Select APIs

Typically prefixed with "get," select APIs return one record for an entity (for example, the getOrderDetails() API returns the details of one order). They do not update the database.

Since select APIs return only one record, they require unique key attributes to be passed in the input XML. If a unique key attribute is not passed in the input XML, the API uses blanks for those attributes in the criteria to select the record. There can be more than one unique key combination, and in that combination you must pass any one of the multiple combinations.

For example, an order is uniquely identified either by the OrderHeaderKey key attribute or by a combination of the OrderNo and EnterpriseCode attributes. So, when calling the getOrderDetails() API, you must pass either the OrderHeaderKey attribute or the combination of the OrderNo, EnterpriseCode and DocumentType key attributes. If you pass only OrderNo, the API returns the order that matches OrderNo and has a blank enterprise code. In order to identify the unique key combinations for each API, see the Javadoc.

However, getOrderDetails() API uses a select for update on YFS_ORDER_HEADER so that its internal processes such as user exits, events, etc., have a lock on the order elements while the thread working on it is active. This enables to maintain a transaction cache until the final commit. Hence, you need to avoid using nested transactions to overcome the locking mechanism by performing:

  1. Commit or rollback only once for all event of the order. Keep in mind that all the events are set to rollback if one of them fails.
  2. Select the order for each event and process. Also keep in mind that if age of the orders having multiple events are higher it could have an impact on the performance.

List APIs

Typically prefixed with "get," list APIs return a list of records for an entity that match the criteria specified through the input XML, for example, the getOrderList() API returns a list of orders. If any attribute in the input XML has a blank value, it is ignored. List APIs do not update the database. You can also get the paginated data from a list API by calling the getPage API and passing the list API as the input to the getPage API. For more information about the getPage API, see the Javadoc.

Update APIs

Update APIs insert new records into the database. They also modify or delete existing records in the database. Update APIs that modify or delete existing records use the same logic as select APIs to identify which record to update. If no record is found, update APIs throw an exception.