An API, or Application Programming Interface, is a set of public functions that interfaces to some set of underlying code that already exists. With an API, a developer can programmatically access existing functionality within their own application. One common example of an API in LabVIEW is the NI-DAQmx Driver API. This API accesses NI-DAQmx compatible hardware and includes functions such as Read, Write, Start, Stop etc. The user of the API usually does not care about what happens inside of the DAQmx VIs, just as long as they complete the function that they want.
In this document we discuss a few things that a developer should consider when designing an API.
One important aspect of a good API is simplicity. There can be hundreds of functions that are available for your application, however not all of them may be completely useful to the end user. It is important to consider which are the most important functions that a developer would want to access to include in the API. You may also include advanced functions, but it can be helpful to make these less prominent to the average user.
Another important consideration of designing an API is consistency. It is important that the different functions within the API have a consistent look and feel so that a developer can easily understand how to use it. Icons should have a consistent look using the same header, color scheme, glyphs, etc (more information on best practices for creating icons can be found here). Connector panes should all have the same or similar pattern (i.e. 4x2x2x4 or 5x3x3x5). VIs should use consistent data types throughout such as type-definition clusters, references etc. All of the VIs in the API should take the common data as an input, modify it if necesary and then output the same data type. Finally it is important to use consistent VI names within the API. Including the name of the API in the VI name can help keep this consistency, and using common terms such as Read, Write, etc can help users easily determine their functionality.
The third consideration for an API is adaptability. It’s important to plan for future expansion and changes to an API. Using typedefs allow changes to enums and clusters to propagate throughout the API without having to modify every individual VI. Also if possible, you should leave some empty connector pane terminals so you can add controls and indicators in the future. Finally it is important to ensure that future additions or changes will not break existing code. For example renaming VIs or rearranging connector panes may make more sense for future development, but will most likely cause any code that calls it to no longer work. More discussion on how to handle these changes can be found here.
The most important consideration for designing an API is usability. If an API is confusing to a new user, it will be much more difficult to get developers to make use of the API. One thing to think about regarding usability is the logical organization of palettes. If you have open and close functions, the open should be on the left and close on the right. Keep the most commonly used VIs at the top of the palette and lesser common or advanced palettes at the bottom or right.
The functions must also be intuitive to use. Make sure that the user can easily determine what the function does based on the name. Use logical names and placement of controls and indicators of the function so that users can easily wire it up and understand what data the function uses. For example, use the word "Channel" instead of "Ch" and use "in" and "out" to help clarify the direction of data flow.
Finally it is extremely important that your API is well documented. Again ensure that you use intuitive control and indicator names, and list default data in parentheses. Functions should have a short description listed in the context help and detailed help should be available for more complicated functions. For more information on this documentation, see Documentation Best Practices.