Training: REST APIs
APIs in EASYProcess are essentially just processes that are directly exposed to the internet rather than having to be run from a user interface. We will now create a simple API that allows the user to retrieve, insert, update, and delete records from a SQL table.
Step 1: Creating the Process
All EASYProcess API calls are directed to a process when they are called. Therefore, creating a process must be the first step in API creation. Creating a process that will be used as an API is no different than creating a process that is being created to run internally. In EASYProcess, navigate to the “Work with Processes” page either by clicking the Work with Processes button on the application home page or navigating to Process >> Process Home on the top menu. Click the Design New Process button on the top right to begin a new process creation.
Give the process a useful, informative name and description. Here we are making an API that will allow us to perform basic operations on the EmployeeLeaveRequest table, so let’s just call this process EmployeeLeaveRequest API. Clicking continue on the Add New Process window will create the process and open the new process canvas.
At this point you can begin designing the process, but here we will map the API to the process before actually implementing any functionality.
Step 2: Mapping the API to the Process
Once a process is defined it must be mapped to an API name before it can be used as an API. First navigate to the Work with Resources page in the top menu by going to API >> RESTful Web Services: Resources and APIs.
We begin by adding a new API using the Add New section at the top left of the page. We need to provide a name for the API call. Here EmployeeLeaveRequest should be sufficient. The active field determines whether or not the API is available to be accessed. Here we will set it to true, but you can leave it set to false while you are working. Just remember to change it back to active when you are ready to test. Click Add to create the new API.
The API has been created, but it is still not ready to use. We still need to map the API to our new process and decide which HTTP verbs to allow as input. To add a new HTTP verb option select your API from the Resource List and click the button at the top right of the Verbs list.
For our purposes, in order to perform the desired actions, we need definitions for GET, POST, PUT, and DELETE. In the Add Verb window we need to select which verb we would like to add. We also need to choose a ProcessId to map to. Here we need to select the process we created in step 1. You can map each verb to be directed to a different process if desired, but here will manage all the cases in a single process. We also need to select a security level for each call type. Here will just leave it at 0.
Repeat this process three more times to add all the necessary verbs. Once that mapping is complete you can return to the process canvas to begin your design.
Step 3: Designing the Process
Designing a process used by an API is almost exactly the same, with the only differences coming in how the inputs and outputs are handled.
Dealing with API Inputs
There are three different input types that you may need to deal with when creating your API process. All the data is still accessed in the same way, the only difference being in which node it appears.
- Input Node: All processes called via API will have an input node. This node will always contain at least a Verb node containing the HTTP verb used in the call. GET and PUT calls will also contain an Id node in the Input node. This is typically used to identify which record the user would like to retrieve or update.
- Query Strings: Depending on how the API is called it may include query string parameters. These will appear in a QueryString node during process execution. For example, a call with query strings of RequestID and Date would produce a result like the one seen below.
- Post Data: POST and PUT calls can contain any number of additional nodes based on the post data provided in the call. These node names will vary based on the names given to the nodes in the process call. For example, if the following JSON is send as post data.
The data in EASYProcess would appear as below.
Building the Process
First, we will create a separate path of execution for each of the possible actions. To do this we simply need to test if the Input/Verb node is equal to a specific verb. Below is an example of what the API structure and sample binary decision would look like.
Next, we need to flesh out each path. The GET request will typically fetch a record if an id is provided, or fetch all available records if the id is left blank. POST will create a new record, PUT will update an existing record, and delete will delete a record if an id is provided, or delete all records if it is blank. A very simple implementation of this process may look something like what you see below.
In practice, the actual implementations may be significantly more complicated as it will likely require additional validation, but those details are being ignored here as they are likely customer specific and not specific to the creation and implementation of APIs.
Step 4: Assigning Outputs
Unlike with internal process calls, only certain nodes from an APIs execution will be made available to the caller. Setting up these nodes requires setting a couple properties of the desired service nodes. Select a node that you would like to be output and observe the properties toolbar on the right of the screen. The values in the REST API section must be set. REST Output is a simple True/False parameter. The selected node will be returned by the process if the value is set to true. The RESTOutputName defines the name given to the node in the output. It doesn’t need to match the name on the process canvas. The RESTIsArray allows you to return multiple records in an array if set to true.
Step 5: Calling & Testing the API
Calling an API is done by sending an appropriately formatted request to the URL at which the API is located. EASYProcess API URLs are the normal application URL followed by REST/JSON/[API Name]. So, for this API we can append REST/JSON/EmployeeLeaveRequest to the end of the application URL to run it.
Note: A list of available APIs can be found by running a GET request on REST/JSON/List