APIs are a foundation of building modular, adaptable applications. An API (Application Programming Interface) is they way that the programming in an application communicates to other areas of programming. Just as a user needs a user interface to interact with the application, the programming needs an interface to interact with other areas of the application. In a car, the steering wheel is the user interface, and the API is how the steering wheel communicates to the wheels to tell them how much to turn.
Using an API to build modular code
Let’s imagine an application that stores financial information. That financial information may be related to projects, or it may be related to departments. The user is going to want to run financial reports on either area, and see the same report of incomes and expenses. One approach would be to develop a script which runs the Project Financial Report, and another script to run the Department Financial Report. Then the user interface has a button for each type or report the user can run.
The inefficiency comes from having to different scripts to do essentially the same thing. This becomes more apparent the longer you work on an application, and the more change requests that come to update the report. Now there are two scripts that need to be updated to achieve the same results. The more complex the application becomes, the more places to look for code to be updated.
The goal is to have one script to run the financial report, with one place to perform the updates for the report. To do this, the user interface needs to communicate to the reporting script which type of report to run, Project or Department. Every FileMaker script can take one text script parameter. A simple solution is to have two buttons for the user interface, one calls the script with a script parameter of “Project”, and the other calls the same script with a script parameter of “Department.”
Complex problems require JSON solutions
In this simple example, only one parameter needed to be passed into the script for the script to know what to do. As applications became more complex, developers needed ways to communicate multiple parameters to a script to improve its function. Perhaps the user wants to run the report on a specific date range, view a summary report on a different layout instead of the full report, or send the report to an email address instead of downloading. All of these and more can be parameters sent to the reporting script as an API. Initially, developers came up with their own formats, such as value lists, with each parameter being sent on a different line. In that case, the developer needs to know, the first line is the layout, the second line is the report type, and the third line is the date. Knowledge that is quickly lost to future developers working on the same application.
Another approach is to have the user set fields, or automatically set fields that the script later reads from to determine the type of report to generate. The developer may also use global variables to pass information in between scripts, since these values persist between scripts. Both of these approaches suffer from what functional programming calls “side-effects”. The script now has a dependency on something outside of the script’s control. Fields and variables can be changed while the script is running, changing the initial intended outcome. Even if this is unlikely, the ideal API passes all the information the script needs to run successfully when the script is initially run.
That means passing all that information into the script as a script parameter, requiring an easy way to set and retrieve in the text format required by the script parameter. JSON (JavaScript Object Notation) is a common format used on the web for storing multiple values in a easily readable text format [LINK: Using arrays in powerful new ways]. An Object consists of a key and a value. In the earlier example, the key might be “report type” and the value would be “Project.” So an object with one key-value pair is {“report type”:”Project”}. Multiple keys can be added without obscuring the readability of which value stores which information. {“report type”:”Project”, “layout”:”Summary”} is an unambiguous way to communicate multiple parameters in a single text statement.
Modules with multiple functions
A couple of important notes about JSON. The keys are case sensitive, if a key was entered as “layout”,you can’t retrieve the value using “Layout”. Another note is that the keys do not stay in a specific order. FileMaker may alphabetize the keys of an object whether asked to or not. If the order matters, then an array should be used instead. An added value of JSON is that it supports nested objects. This allows the parameters to be complex and concise. From the example above, the application may have a report function that handles all the exports for the application in a consistent and reliable way. And perhaps this Report script can run multiple reports at the same time and prepare them for email. This is where we can introduce functional parameters as an extension of the basic script parameters.
Functional parameters encapsulate the function and information needed to run the script successfully. Instead of sending a series of key values, we send a series of functions, with nested parameters of the information that each function needs. In practice, the example above might look like {“Project Report”:{“layout”:”Summary”, “date”:”March”}}. This API tells the Report script to run a project report, use the Summary layout, and report on the month of March. Now each report type uses a nested object to communicate the parameters the user wants. FileMaker allows developers to specify nested objects with a single function using bracket or dot notation. [LINK TO FM JSON] Bracket notation is recommended, since it can handle keys that have dots in their name. To create the nested JSON Object above, use a single JSONSetElement function shown below.
JSONSetElement ( “”;
[ “[‘Project Report’][‘layout’]”; “Summary”; JSONString ];
[ “[‘Project Report’][‘date’]”; “March”; JSONString ])
One Comment