You can use both standard APIs that are supplied by the application and any extended (custom) APIs that you have created.
IBMÂ® Order Management provides standard APIs to handle the most common business scenarios. For example, there are APIs that create an order, allocate an order, and report shipment confirmation. Standard APIs can be invoked directly or aggregated into more complex services. The standard XML APIs (XAPIs) can be accessed through a REST layer with HTTP requests.
Each API takes an XML document as input and returns another XML document as output. APIs can be asynchronous or synchronous.
The YFSEnvironment input parameter represents a runtime state under which this API is being invoked. It is used for the following tasks:
- Security audits and logging
- Transaction control
- Achieving invocation-specific API behavior
For an asynchronous service, IBMÂ® Order Management automatically creates an instance of this object and passes it to each API part of the service. To programmatically invoke a synchronous service, you have to create an instance of this environment by calling the createEnvironment() API.
Note: In general, input to APIs should not contain any “BLANK” elements or attributes. A blank element can be defined as an element containing all the attributes with blank values. If a blank element is passed, the API behavior is unpredictable.
All APIs (whether standard or extended) have the same signature with respect to input parameters and return values. This signature is of the form
org.w3c.dom.Document APIName(YFSEnvironment env, org.w3c.dom.Document input);
In order for custom APIs to access custom values, the API should implement the com.yantra.interop.japi.YIFCustomApi interface. If entered, these name/value pairs are passed to the Custom API as a Properties object. See the Javadocs for more information about the com.yantra.interop.japi.YIFCustomApi interface.
You can secure your APIs with two different levels that allow you to control who can call APIs and what authorization that person must have.
When calling an API, you must pass through the following two levels of security:
- Authentication with a user ID, a certificate or both. The login API is called before any other API is called.
- Authorization, which verifies which API that you can access.
This security procedure is for every API call that is made through an application server process. By default, agent and integration servers always have full access to APIs.
Once you have passed the authentication check, an authorization check determines what APIs and resources you can access. This authorization check is in addition to the user interface (UI) security. For example, the UI security might allow you access to a screen that lists users. To generate a list of users at the screen, you might also have to pass an authorization check for the getUserList API that lists the users.
Other examples of authorization checks include:
- If you use the getCommonCodeList API for display purposes, you should not be able to get user information that is explicitly restricted from the output of the API.
- If you call the getUserList API before assigning an alert, you should not be able to get user passwords.
- If you use the UserHierarchy API to change your password:
- You should not be able to change your own IsSuperUser flag.
- You should not be able to modify another user’s information.
- You should not be able to subscribe to additional user groups, which would give you more system access.
This security is implemented using the apisecurity specific template files. These apisecurity template files are XML files that documents the input and output elements to which (by default) all APIs are restricted. These files are automatically generated during XAPI deployment, even when document generation is turned off.
Note: Services do not use the apisecurity file.
Templates are used for the input and output authorization checks. These templates override the regular templates.
For example, an input template with the lines
IsSuperUser=#PROHIBITED# would prevent you from subscribing to more user groups and gaining more permissions.
The output template supplements the filtering performed by the default documentation-based template. If an element is restricted because it is not configured in the apisecurity file, it will never be returned in the output, even if present in the documentation-based template.
Note: At certain points in the input and output, APIs like multiApi and getPage have authorization access for any element. But other APIs that are called by these APIs must go through the authorization check.
Access to API security and the permission level are controlled in the following properties in the yfs.properties file. All authorization failures are logged to a logging category named sci.apisecurity.
- Y (default)—Enable API security
- N—Do not enable API security
- STRICT—If any validation fails, throw an exception. This is appropriate for production systems, if all permissions are configured properly.
- LAX—Filter out and log invalid input, but continue processing. The filtering allows the system to mostly work despite incorrect input or output, while the logging helps to identify places that need change.
- DEBUG—Log invalid input and output, but do not filter anything or throw exceptions. This is only appropriate during initial development, to identify the permissions required by various processes.
Note: The system may still throw an exception when the filtering produces an ambiguous behavior.
If you do not specify a security mode, there is no filtering, thrown exceptions, or authorization checking. There is limited logging.
Use this setting to override permissions on individual APIs. This property uses the same values as api.security.mode.
- Y—Enable API security for the Application Console
- N (default)—Do not enable API security for the Application Console
- Y—Enable API security for the Application Console
- N (default)—Do not enable API security for the Application Console
When upgrading, you should initially disable this feature and grant all access through properties. In an upgraded system, you can phase in this feature by enabling security one API at a time, as you define and test permissions. If enabled, only the system user group has grant permission to the APIs; for all other custom user groups, appropriate permission has to be given. For information about user group permissions, see Organization and participant modeling concepts.
For information about including the apisecurity file in the documentation and building it into the EAR, see Including the api security file in the documentation.
Date and time handling by APIs
The application handles values for both date-time and date. Date-time refers to values that contains a date and time component, where Date refers to values that contain only a date component.
Date values can be made nullable by specifying
Nullable="true" in the entity XML. Thereby the Date values in the table is blanked out. The expected behavior of a date column is marked as
Y is described in the following table.
|Insert||When the field is not populated in a database object (is null), the database infrastructure automatically inserts a null value into the column in the database.|
|Update||When the application nulls out a date, it sets the corresponding field to null value in the database.|
|Select or List||When a column is defined as nullable and the date from the database is returned as null, it is automatically nulled out. So, the corresponding get method returns a null.|
|Search by date||Can pass null value as needed when specified to do so.|
Note: If you have specified the date value as 01/01/2400 in versions prior to Release 8.5, those values are now treated as null. The dates with special significance are:
- Null date – 01/01/2400
- High date – 01/01/2500
- Low date – 01/01/1900
Specifying time zones
Dates and times are time zone aware. Time zones are relative to the Coordinated Universal Time (UTC).
For example, if an order is created on the system on 06/15/2003 at 16:00:00 in New York, (USA/New York time zone) a user in Chicago who examines that order observes that order creation date-time as 06/15/2003 at 15:00:00, (USA/Chicago time zone).
For a time published from Boston that is -5:00 hours from UTC, the string literal “-5:00” is appended to the current date-time attribute published from APIs. The input “2003-04-23T14:15:32-05:00” gives the date, time, and time zone reference for a transaction.
The yfs.install.localecode parameter in the
yfs.properties file determines the application time zone. For example,
To configure the time zone, set the yfs.install.localecode property to
en_US_EST in the
Using date-time syntax
All APIs, user exits, and events that use date-time fields have a uniform syntax (a combination of the basic and extended formats of the ISO 8601 specification). This syntax is the expected format for all input as well as output.
Date only syntax
Using Date-time syntax
YYYY–MM–DDTHH:MI:SSZ or YYYY–MM–DDTHH:MI:SS+HH:MM
Values in bold above are placeholders for literals. For example, the format for March 5, 2003, 11:30:59 p.m. is 2003-03-05T23:30:59.
Note: This syntax is an ISO Date-Time syntax and not the database syntax. Using a syntax other than the ISO Date-Time format may cause problems. For example, the time element in the Date-Time syntax may be overlooked or calculated incorrectly.
For example, if you provide the Date-Time input as “2007-05-18-19.10.28.000000”, the system may interpret it as just “2007-05-18” because the T symbol is missing in the input.
||Required. Four-digit year. Used in both date-time and date fields.|
||Required. Two-digit month. Used in both date-time and date fields.|
||Required. Two-digit day of the month. Used in both date-time and date fields.|
||Required. The literal value T, which separates the date and time component. Used only in date-time fields.|
||Required. Two-digit hour of the day. For example, 11 p.m. is displayed as 23:00:00. Used only in date-time fields.|
||Required. Two-digit minutes of the hour. For example, 59 minutes is displayed as 00:59:00. Used only in date-time fields.|
||Required. Two-digit seconds of the minute. For example, 21 seconds is displayed as 00:00:21. Used only in date-time fields.|
Optional. This parameter separates the time component in GMT format. Used only in Date-Time syntax.
Note: You can pass the parameter Z as input. The system does not return this parameter in output.
||Optional. Two-digit hours and minutes, separated by a colon (“:”). Indicates how many hours from UTC, using – to indicate earlier than UTC and + to indicate later than UTC. If this value is not passed in input, the time zone of the application is assumed.|
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.
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 Javadocs.
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.
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 Javadocs.
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.