After reading this article, you’ll know how to:
-
Use the Format endpoint result step in actions
-
Give a proper response to your users
Getting started
Install the Format endpoint result step from the Block Store. You can read more about installing blocks in this article. To test the action step, we recommend using an API platform such as Postman.
Format endpoint result step is a useful tool for providing feedback (response) to your users. For example, when you send a POST request to an action (endpoint) in Betty Blocks, it is beneficial to receive feedback such as the status code, headers, and body.
Did the request process as expected (200), or did something go wrong (500)? In the headers, you can specify the content type like JSON. In the body, you could return the record that we created based on the requests input. You can define all of this yourself in the action step.
A prerequisite to follow along would be already to have an employee model with the following properties:
Creating a schema model
A good use case to understand how this action step works would be to create an employee record via a POST request using Postman. For that, we'll first need to create a schema model in Betty Blocks. Call it something like RequestSchema and add the following properties:
These variables are needed to work with the Format endpoint result step. We'll use this schema model in the action we'll create next.
Add the schema model to your action
Create a new action, the first thing we'll do is add a request variable in the start step, to make sure our newly created schema model can be read in the action like so:
Select the newly created schema model here. Before we continue with the next steps of this action, let's dive into the request that this action is going to process.
Creating the request
For this use case, we'll create the POST request that will be sent to our action. The URL needed to make a POST for the format endpoint result step requires an app-identifier, this is the name of your application. The UUID of your application and the action ID of your action (the string of letters and numbers after /actions/ are in the URL when you have an action open).
<app-identifier>.betty.app/api/runtime/<app-uuid>/action/<action-id>
Example of URL that we'll use in this case:
obsidian.betty.app/api/runtime/32d9eb0140ea4a06a141f3b4a99bc48e/action/cabdd9dec91743dc9ae130daceff06c7
Assuming that you're using Postman, make sure to set the method to POST:
Now select the body tab followed by the raw checkbox, this allows us to select JSON in the dropdown that appears.
We can now specify the actual data that we want to submit. This should be a new employee according to the properties within the employee model.
With our POST request ready to go let's continue with the action that will process this data.
Continuing with the action
When you install the Format result endpoint step, you'll notice that a second step is also added namely the JSONPath step. This is the step that will chop the request we created using Postman apart and transform it into bits that we can use in our action. It will make more sense in a second.
Drag the JSONPath step on the canvas, select the request variable we created earlier, the data in our request is within the body so make sure to select that here.
The first property in our request is the name, the path is as follows: $.name the output type is plain text, and give the result of this a name like so:
If you want to learn more about the syntax of JSON path then make sure to check out this GitHub page.
Let's do the above for email and date of birth as well.
 |
With the bits of data that we can work with in place, we can create a new employee record based on the values we retrieve from the request. Drag a Create step in our action and configure it like this:
Now we can configure the Format endpoint result. What we'll return to the user making the request is the newly created employee and a status code. For the step to work properly, we also need to define the headers, so in our example, we need to specify that the content type is JSON just like the image below:
Give the result variable the name response and add it to the Finish step. The action that we created looks like this now that we're finished.
Sending a request
To verify if everything is working as intended, let's send the Postman request we set up earlier. If you still have Postman, open the tab and press the Send button to pass the data of the new employee to the action we just created.
If everything is working as we expect, then we should see the data that we set up in our Format endpoint result step.
And as expected, that's our new employee Chuck. We can confirm it even further by creating a page in our application to see if Chuck shows up among previously added colleagues.
As we can see in the image above, he shows up here as well.
Retrieving information
As a bonus, let's also create an action that retrieves the data from our employees. Copy the ID of the action as we did with the POST request and change the Postman request URL so that it calls this new action.
Creating the request
Next within Postman, we don't need the body tab anymore instead, when we want to retrieve information (GET), we specify this in the request URL. It means we'll work with the path variable instead of the body. So on top of changing the action ID, we need to add a bit more data namely '/employees/id' where ID is the ID of the employee you want to see the data of.
If we want to see the data from Chuck (ID 8), the URL will look something like this:
obsidian.betty.app/api/runtime/32d9eb0140ea4a06a141f3b4a99bc48e/action/4e740000d2064b3f8148afceddd5b44e/employees/8
The /employees/ part isn't strictly necessary but it's a best practice to create your URLs this way. We could also simply just have /8 and still retrieve Chuck's data but the other way makes the URL more readable.
Creating the action
All right in the action, like before, create an input variable of the type object and call it request.
Next up, we'll use the JSONPath step again, this time since we're not using body but path select that from the request.
The JSONPath is a bit different since we're using a more readable URL meaning we retrieve both 'employees', and 'id' in our request. This means we need the second item (the ID), hence we're using $[1]. If our URL was just /8 without /employees/ then $[0] would suffice. Read more about this on the following GitHub page.
Regardless, using the JSONPath step the result will now contain the ID of our employee. To return the object of the employee, we'll need to use the Format endpoints result step. Drag it on the canvas and go to the variable tab (next to the options tab). Create a new object using a filter as follows:
This will contain the data of the employee with whatever ID we specify in our GET request. We can now give this object back in the body of the Format result endpoint like this:
Add the response to the Finish step.
Sending the request
Let's get back to Postman and send the request to this new action to see if we retrieve the data of our employee.
And there we go, we can see the data of Chuck:
If instead of 8, we'd change the ID to 2 we'd see the data of Jerry!
Anyways, these small examples made sense enabling you to use these steps in your use cases. Happy building!