Types of APIs
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:
- 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.
- 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.