APIs overview

Who should use APIs

APIs are intended for experienced application programmers to develop system-level and other IBM i applications. The API information provides reference only. It is neither an introduction to IBM i nor a guide to writing IBM i applications.

How the API information is organized

The API information can be found either by the API name through the API finder or by category through the API categories page.

In the API finder, you can search for APIs by category, by API name, by descriptive name, or by part of the name. You can also search for new APIs, changed APIs, and exit programs.

The API categories are major functional categories, such as backup and recovery, objects, and work management. Within the individual categories, the APIs are organized in alphabetical order as follows:

• By the spelled-out name for the program-based APIs, the service-program-based APIs, and the Integrated Language Environment® (ILE) Common Execution Environment (CEE) APIs.
• By the function name for the UNIX-type APIs.

Compatibility with future releases

IBM intends that the APIs will continue to work as they originally worked, and any existing applications that use the APIs will continue to work without any incompatible changes. Significant architectural changes, however, might necessitate incompatible changes.

Additionally, some API definitions, such as the UNIX type of API definitions, are established by industry standards organizations, where the degree of compatibility is determined by the organizations.

In future releases, IBM also intends that one of the following statements is true:

• If additional input or output parameters are provided for any of the APIs, the new parameters will be placed after the current parameters and will be optional parameters. The existing APIs will continue to work without any changes.
• If an additional data structure is provided, a new format (layout of that data structure) will be created.
• New information might be added to the end of an existing format.

To ensure better compatibility with future releases, retrieve and use all of the following values when you work with user spaces that are generated by list APIs:

• Offset values to the list data section
• Size of the list data section
• Number of list entries
• Size of each entry

System APIs or CL commands--when to use each

An API is designed to be used as a programming interface, and a CL command is intended to be entered either interactively or in a CL program.

Before system APIs were offered on the system, you had to either code separate CL programs to perform the needed functions using the appropriate CL commands or code a call to the Execute Command (QCMDEXC) API in your program. Both methods made coding an application on the system more cumbersome (less straightforward and not as fast as possible).

CL commands will always be needed; they are ideal for the interactive user and for CL applications that are performing basic tasks. They provide a complete set of functions on the system.

APIs are not provided as a replacement for CL commands, although in many cases there might be both an API and a CL command that perform the same function. If a CL command and an API provide the same function, at times the API provides more flexibility and information.

Some APIs have no equivalent CL commands. These APIs have been provided in areas where customers and business partners have indicated that they need high-level language (HLL) access.

Actions and system functions of APIs

An API can be categorized by the type of action it performs and by the system function that it relates to.

Listed here are some of the types of APIs that perform actions; several examples of these APIs are discussed in more detail in later topics.

• List APIs, which return lists of information about something on the system.
• Retrieve APIs, which return information to the application program.
• Create, change, and delete APIs, which work with objects of a specified type on the system.
• Other APIs, which perform a variety of actions on the system.

Although many APIs are used alone, some APIs can be used together to perform tasks or functions as in these examples:

• Defining, creating, distributing, and maintaining your own software products.
• Controlling systems and networks, which includes configuration, spooled files, network management, and problem management.
• Handling objects, which includes creating, changing, copying, deleting, moving, and renaming objects on the system.