APIs Introduction

Content Information

The VistA Infrastructure (VI) Application Program Interfaces (APIs) contents list can be displayed in the following four ways:

1. Category List:
   
   APIs are listed alphabetically by category type (default). Within each category, APIs are then listed in alphabetical order by routine name of the entry point. Within each routine grouping, APIs are then listed in alphabetical order by tag name of the routine entry point.
   
   
2. Routine Names Alphabetic List:
   
   APIs are listed alphabetically by routine name. Within each routine grouping, APIs are then listed in alphabetical order by tag name of the routine entry point.
   
   
3. Tag Names Alphabetic List:
   
   APIs are listed alphabetically by tag name of the routine entry point.
   
   
4. Reference Type List:
   
   APIs are listed by reference type (i.e., Supported or Controlled Subscription). Within each reference type, APIs are then listed in alphabetical order by routine name of the entry point. Within each routine grouping, APIs are then listed in alphabetical order by tag name of the routine entry point.

API Information

Each VistA Infrastructure (VI) API displays the following information in the order listed:

1. API Name (required):
   
   This is the name of the API and is followed by a colon and a brief descriptive phrase of its use. It is written in one of the following formats:
   
   
   • ^ROUTINE or TAG^ROUTINE—This format is used when the API is an entry point that does not take any input parameters in a parameter list (i.e., no parenthesis following the routine name).
     
     
   • TAG^ROUTINE()—This format is used when the API is a procedure. Parentheses following the routine name indicate that the API may take input parameters.
     
     
   • $$TAG^ROUTINE()—This format is used when the API is an extrinsic function.  Parentheses following the routine name indicate that the API may take input parameters.

   For example:

       MAIL^XLFNSLK(): Get IP Addresses for a Domain Name

   In this case "MAIL" is the tag name, "XLFNSLK" is the routine name, and the parenthesis indicate that this API may take input parameters. The lack of "$$" preceding the tag name indicates that this API is a procedure. The brief text that follows the colon gives you a general idea of what this API does.

   Another example:

       $$ADDRESS^XLFNSLK(): Conversion (Domain Name to IP Addresses)

   In this case "ADDRESS" is the tag name, "XLFNSLK" is the routine name, and the parenthesis indicate that this API may take input parameters. The "$$" preceding the tag name indicates that this API is an extrinsic function. The brief text that follows the colon gives you a general idea of what this API does.

2. Reference Type (required):
   
   The Reference Type indicates the Integration Control Registration (ICR) for the API:
   
   
   • Supported Reference—An API of this type is open for use by any VistA application. It has been recorded as a Supported Reference in the IA database on FORUM. VistA software applications do not need to request an IA to use it.
     
     
   • Controlled Subscription Reference—An API of this type is controlled in its use. Permission to use the API is granted by the custodial package (software application, such as Kernel) on a case-by-case basis.

   NOTE: Private APIs are not documented in this manual.

3. Category (required):
   
   The Category indicates the general category to which the API belongs.
   
   
4. Integration Control Registration (required):
   
   The Integration Control Registration indicates the Supported or Controlled Subscription Reference Integration Control Registration (ICR) number for the API.
   
   
5. Description (required):
   
   This section provides an overall description of the API. Please include the patch reference ID (e.g., XU*8.0*999) if this API is being released via a patch.
   
   
6. Format (required):
   
   This section displays the format (usage) of the API. Optional parameters appear inside rectangular brackets [ ]. For example, tag^routine(x[,y]), the x input parameter is required and the y input parameter is optional. Rectangular brackets around a leading period [.] in front of a parameter indicate that you can optionally pass that parameter by reference.
   
   
7. Input Parameters / Input Variables (optional):
   
   This section lists all input parameters/variables for the API:
   
   
   • Input Parameters—Input passed in a parameter list to procedure and function APIs. For documentation purposes only, parameters are shown in lowercase.
     
     
   • Input Variables—Input variables passed through the symbol table to APIs without a parameter list.  For documentation purposes only, variables are shown in uppercase.

   All input parameters must indicate whether they are "required" or "optional."

8. Output / Output Parameters / Output Variables (optional):
   
   This section lists all output or output variables returned by the API:
   
   
   • Output—Output returned through a "pass by reference" variable from a procedure or the return value of an extrinsic function API.
     
     
   • Output Parameters—Output parameters returned by the API.
     
     
   • Output Variables—Output variables returned through the symbol table from an API.
     
     
9. Details (optional):
   
   This section provides any additional  information regarding the use of the API. This should include anything not already included in the API "Description" section.
   
   
10. Examples (required):
    
    This section provides one or more examples demonstrating the use/functionality of the API (not all APIs have examples).