Application Program Interface (API) Pattern

An Application Program Interface (API) is a set of calling conventions that defines how a service is invoked through software. An API enables client programs written by users or third parties to communicate with a server application via a defined interface. APIs have several key characteristics:

• Data is exchanged via services (procedural code). 
• Most operations involve complete business objects, which may be complex.
• Extensible Markup Language (XML) is used to encode the data in most cases.
• Commit / rollback is typically controlled by the service-providing application.
• Error and exception handling is handled by the enterprise application service, with the appropriate return code being passed back to the client.

The API pattern provides a standard approach to creating loosely coupled interactions between systems that must be integrated. The key components of the API are:

• Client Application – The client application access the API presented by the server application.
• Server Application – The server application presents the API for use by client applications. 
• Interface – The interface is the “contract” defining the semantics that must be used by the client to access the server and the format of the results that will be returned.

An API may involve synchronous or asynchronous request-reply interactions. The server may immediately send a response message to the requesting client application, or an asynchronous acknowledgement message may be sent to the client application at a later time using a message queue or some other callback mechanism.

This pattern can be thought of as a basic component that is used in the many of the more complex Integration Technology patterns within the NIH architecture.

Please view the API Pattern below:

• Provides the basic building blocks for reusable services.
• Enables clients and services to be written in a wide variety of programming languages.
• Provides benefit to extension system developers be leveraging a standard approach for APIs.
• Provides transport of whole “business objects” (e.g., entire purchase orders or invoices), rather than line items, will optimize network usage.
• Complies with the “loose coupling” integration principle.

Security and audit requirements must be defined for shared APIs with a focus on:

• Determining how client applications will be authenticated.
• Determining whether encrypted communication is required between client and server.
• Determining how access to the API must be recorded and reported on.

Recommended Usage

• An API should be defined in all cases where request-reply interaction is required between two systems at the application level. Database to database interactions are managed through the Data Consistency Pattern.
• APIs are logical patterns that serve as the basis for more advanced integration. The API pattern can be observed in the following patterns - Service-Oriented Architecture (SOA), Composite Applications, Enterprise Service Bus, Web Services and Service Implementation.
• Web Services and SOA are the preferred approaches to implementing APIs within NIH. Other approaches may be used for small-scale or point-to-point integrations using homogeneous technology platform (e.g., both integration end-points are J2EE based).

API implementation can be facilitated through the use of the Enterprise Service Bus (ESB)/Integration Broker Suite (IBS).