API: the inside story

 API is a popular keyword in programming. API stands for Application Programming Interface. It is commonly used for implementing any programming technology such as file handling, network socket programming or database connectivity. Though many programming languages offer API's, a generalized understanding about the API would be technologies and smooth migration between programming platforms. 

API seems to be very much similar to the built-in libraries of programming languages, comprising in-built functions to perform certain operations. However, an API differs from an ordinary library in below aspects: 

• An API interfaces programs with any system concepts, resource or hardware programmatically whereas a programming library simply offers data manipulation through some built-in functions. 
  

• The functions defined in as API commonly resemble certain operations on some resource. Hence, one must call those functions as per the order given in its life-cycle specification. In contrast, a commonly a library function may be called irrespective of order. 

• For practicing an API in programs, one must learn the operation of its backend resource. However, for using a library, one must know the prototype specification and data type of the functions of the library. 
  

• Most commonly, the implementation of an API is kept hidden by allowing concrete data types and factory functions to be used by the programmers rather than accessing the data members of those data types directly. Factory functions are useful for hiding the resource data type implementation. For example, due to a factory function fopen(), you will never know that FILE is a predefined structure. You believe that it is a natural data type. 

• API's are commonly designed by the vender of the resource whereas libraries are shipped with programming language tools. 
  

An API can be characterized with below features: 

Life Cycle - since the primary interest of an API is to interface with a resource or system concept; accordingly a life-cycle specification is provided. For example, for file-I/O, we must follow the order of opening buffers, performing I/O and closing them. One cannot perform I/O without opening the buffers. Thus, programmer is restricted to follow a predefined order for the usage of API functions. 

Data types - If an API is meant for the interaction with a system resource or hardware, there must be a data type defined in that API to resemble that resource or hardware. For example, file-I/O API contains FILE data types may be C structures, Unions or C++ classes, which depends on the programming language for which API is written. 

Handles - Although resource data types are given, their variables cannot be directly used to process the resource. One solution is to use the same data type pointers as handles. For example, to send a file can be used. Sometimes, the underlying resources may not any memory or attributes to be explicitly maintained. For such resources, handles can be simple integers comprising their identification details, rather than its data type pointers. For example to handle sockets, we use an integer called socket descriptor. 

Factory Functions – A Function that creates a certain user-defined type variable’s instance and returns its handle is known as a factory function. The primary use of these factory functions is to avoid the code overheads for initializing the attributes of the data type. The handle returned by the factory functions can be captured into a program variable. For example, fopen is a factory function that returns a FILE pointer. 

Life Cycle Functions – For changing the state of the resource and to make certain standard operations on the resource, few life-cycle functions are defined in API. For example, to close the file buffer fclose(), to rewind the pointer to update or clear the buffer fflush(), etc. the Life-cycle functions may not be used for data transfer with respect to the resource, rather they may not be used to control the resource. 

Resource-I/O functions – With few resources such as files, network sockets we may need to make data transfers. API provides few resource-I/O functions for this purpose. For example, fprintf() and fscanf() are used to make file-I/O. 

Transformation functions – sometimes one particular resource may be represented with multiple data types with different formats. In such case, conversion or transformation between them is possible through transformation function. For example on UNIX/LINUX Platforms time is represented by using two data types: time_t represents long format time and struct tm represents formatted time. The function localtime() converts time_t type time into the other type. 

Constants – To represent certain predefined, fixed or constrained values, few constants such as macros are defined in API's. Eg: SEEK_OFFSET, SEEK_BEG, SEEK_SET.

To make a set of specification and designs primitives for writing API's and when to take a factory function and when to take an initialization function. 

From the API user's point of view, how do you exploit the various features of an API, and use its constructs for your level best.