Tutorial 2: Create a Capacity App, with APIs for Interacting with Data
CapacityDB is a Capacity-hosted database that can conveniently and seamlessly integrate with the full Capacity tech stack and our customers’ mission-critical applications. Through an engaging and intuitive interface, even novice users will be able to create, update, and take action on useful data sets.
If you have any questions, contact support@capacity.com.
This tutorial builds on the data and queries created in Tutorial 1. In order to continue, you'll want to have first completed the steps at https://support.capacity.com/article/660535/tutorial-1--create-a-capacitydb-table--add-data--and-write-queries.
Creation of App and APIs
First, open the Capacity Web Console, and navigate to the Developer Platform, which has an icon that looks like three stacked sheets of paper.
Click the "Create New App" button, and name it "Delmar Widgets". This app will be the bridge between your data and other parts of the Capacity platform, including Guided Conversations and Workflows.
Click on your app to open it.
In this tutorial, you'll only create APIs for a local app. But you'll notice that the Developer Platform allows for much more, including adding custom settings, Oauth configs, and even Scripts.
Click the "Add New API" button, name it "Get All Widgets" and confirm creation.
On the API Builder screen, match the selections and values in the following screenshot. Be sure to:
- Change API method to "POST", because you're sending instructions to CapacityDB.
- For API endpoint, enter this as the target location for your action:
{{sys.relay_host}}/?service_name=capacitydb&service_path=/api/v1/stored_queries//execute- Replace with the id of the Get All Widgets query. You can find that value by navigating to CapacityDB's Queries tab, and examining the URL in your browser's address bar. It will look something like: https://webui.capacity.com/db//queries/. Also note and remember your Org ID, because you'll need that in the next step.
- In the "Body" tab of your API's information, enter the following, substituting your Org ID. We'll continue to build this out for more complex operations, but for now you can leave "parameters" blank.
{
"org_id": ORG_ID_HERE,
"parameters": {
}
}
Next, navigate to the "Headers" tab, click "Add Row". Enter "Content-Type" for Key, and "application/json" for Value. What you're doing with this is telling CapacityDB that you'll be communicating about your widgets in a structured format, called JSON.
Your API is now ready for testing! Your new app should be able to use the API to execute your query and find your data! Click "Test API" to make sure that it returns information for all of your widgets.
Next, note that you can create outputs with the data returned from the API. Use the "Add Variable" button to create outputs with the JSON Path, Data Type, and Display Name values shown in the screenshot below. The values for these variables will give you useful feedback when searching data in CapacityDB.
Next, add an output of the "List Map" type with the JSON Path and Display Name values shown in the following image.
If you click the "Add Keys" button, you'll see a popup where you can define subpaths for the objects in your list.
Occasionally, the popup won't load properly. If this happens, just reload the page and retry.
Enter the values shown in the image below to add the keys for your widgets, and click "Save".
After you've done this, the red "Add Keys" button should disappear. Click "Activate API" and return to the App
Back on the App page, you'll notice that you now have an active API called "Get All Widgets". Click the icon with the plus sign, to the right of that listing, to clone the API.
Confirm and duplicate the API.
Note that the API is called "Copy of Get All Widgets" by default. You'll want to rename that first.
Select the API and change the name to "Get Widget by Name" and click the "Save Changes" button to confirm renaming it.
Then modify the API body JSON to match the image below. This will automatically create an API input, which will allow you to programmatically insert a search term (in this case, the name of a widget).
You'll also need to update the query ID in the API Endpoint to match the query ID for "Get Widget by Name". Remember that you'll need to go back to the CapacityDB queries tab to retrieve the value. Also, make sure that your Org ID matches your unique Org ID.
This time, for "Test Value", you'll need to provide a sample input. Enter the word "gear" and click "Test API".
All output variables should be set already, since you duplicated them from your first API call. However, this time, the API should only return gears.
Click Activate API and return to the App's list of APIs.
This time, duplicate the API, name it "Add New Widget", substitute the query ID for your Add New Widget query's ID, and ensure your Org ID matches.
This time, you'll need to add more parameters to add widgets to your table in CapacityDB. Copy the API Inputs shown below, and add the matching Test Values.
Click Test API, and you should see a response that looks different. There's no error and no results are returned.
Delete the List Map. When a record is created, no value is returned for "rows".
Next, Save Changes and click "Activate API".
Publishing the App
Click "Publish App", select the first radio button to publish it privately, and Save Changes.
Next, you'll see a popup, with a success message. This means that the app can be installed in your organization and used across other parts of the Capacity platform.
Installing the App
Navigate to App Center next, and toggle the switch next to "Delmar Widgets" to green.
You'll see a blank popup. Some apps require custom settings, but this one does not, so just click "Save".
Congratulations! You've now created your first Capacity app, which will allow you to browse, search, and add widgets!