Content Information

The 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 API will display the following information in the order listed:

1. API Name (required)
   
   This is the name of the API and will be 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 Agreement (IA) 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.
     
     
   
   
   
3. Category (required)
   
   The Category indicates the general category to which the API belongs.
   
   
4. Integration Agreement (required)
   
   The Integration Agreement indicates the Supported or Controlled Subscription Reference Integration Agreement (IA) number for the API.
   
   
5. Description (required)
   
   This section provides an overall description of the API.
   
   
6. Format (required)
   
   This section displays the format (usage) of the API. Optional parameters will 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. Parameters are shown in lowercase.
     
     
   • Input Variables—Input variables passed through the symbol table to APIs without a parameter list. Variables are shown in uppercase.

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

   
   
   
8. Output / 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 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.
   
   
10. Examples (required)
    
    This section provides one or more examples demonstrating the use/functionality of the API. At this time, not all APIs have examples but the "Example" heading is listed a s a placeholder for future examples.