Actions & Events
Learn how to build custom API Endpoints using Actions & Events
We saw in the last section how to use the API Generator to build CRUD endpoints. The API Generator is great for speed, but often you'll want to build something more custom. Combining Custom Endpoints with Actions & Events lets you build just about anything custom inside Dittofi.
In this section we are going to look at:
- 1.Custom endpoints
- 2.Actions & events
- 3.Next Steps
To build a 100% custom endpoint go to your endpoints tab & (A) click "+ New Endpoint" & (B) choose the option "New Endpoint".
This brings up a completely empty endpoint, as below.
Let's walk through each of the basic options quickly to understand at a high level what each of them are for.
Basic Option | Description |
Name | The name that you give to your endpoint. You should pick something meaningful like "make payment" or "get a list of shoes" so that you remember what the endpoint is for, |
Path | The URL path you give to your endpoint. It is best practice to start your path with something like "/v1/..." or "/v2/...". The "v" & number combination indicate the version number of the endpoint. |
Description | A more detailed description of your endpoint. This is used when we automatically generate your API documentation later in the process. |
Request method | There are four types of request method that you can make: GET, POST, PUT & DELETE. We will look at each of these in more detail later on. |
Res. Content Type | The response content type that you endpoint will return. The options are JSON, CSV & HTML. |
Req. Content Type | The request content type that your endpoint can recieve. The options are JSON & multi part form data. |
Auth. Profile | Tells us if a particular endpoint requires a certain level of authentication to access. |
For the purpose of this example, we are going to use the data model below.
We are going to build a custom endpoint to insert a record into this data table.
To do this, you first need to set the basic options for your endpoint. To do this, give you endpoint a name, path, description & set the request method to POST. This is shown below.
Notice, the Res. Content Type, Req. Content Type & Auth. Profile should be left in their default settings.
We select the Request Method "POST" because we want our endpoint to POST or CREATE a new record into our database. At a high level, the image below explains what we are looking to accomplish.
In order for our endpoint to accept data to put into our table, we need to configure our endpoint to be able to receive data. To do this, we use the Variables section at the bottom of our endpoint.
Let's quickly walk through each of the variable options to quickly understand at a high level what each of them are for.
Variable Option | Description |
Body Variable | The variable that is received by the endpoint in the body of the request. |
Header Variables | |
Path Variables | |
Query Variables | |
In our example, we are looking to set up our endpoint to receive a collection of data that we will insert into our data model. The most appropriate variable type to use here is the Body Variable.
To set this up (A) click on the link icon & (B) configure the body variable.
Press save & close. The endpoint is now setup to receive data.
By itself, the endpoint does nothing. It is simply sitting their waiting to receive data & once the data is received, the endpoint doesn't know what to do with it.
In order to take the data & insert it into our Shoes data model we need to link our endpoint to an action. The action will then start a sequence of steps called "Events". The events are actually what will insert the data into our Shoes data model. A visual description of this is below.
To create your action, go to the actions tab inside the Dittofi Design Studio.
To create a new action (A) press "+ New Action" & (B) give your new action a name & press "Save".
This creates & opens a new action. An action is split into two parts. On the left you can find the global settings. On the right you find the actions & events graph.
Starting with the Global Settings. You can see that this is split into three sections.
- 1.Basic
- 2.Advanced
- 3.Variables
The Basic options get filled out automatically when the action is created.
Under the Advanced options there are different options for each trigger. The trigger sets the conditions when the action should run. Actions can be triggered either by endpoints, other actions or run on a schedule.
In our case we want to trigger our action when our endpoint "/v1/create_shoe" receives data. So, we must (A) pick the Trigger Endpoint & (B) set the trigger Endpoint to Create new shoes. For now we will ignore the Resp Variable.
The Variables section allows you to create variables that are accessible from anywhere within your action.
In our example, we don't need a variable.
IMPORTANT: you must save your action at this point, BEFORE adding your event.
Next, we need to add a create event to our actions & events graph. To add an event click the "+" button on the actions & events graph.
From the slide out, you're able to pick the kind of event that you want to run when your action is triggered.
There is a comprehensive list of events here including, Create, Update, Assign, Send Email, HTTP Request & many more. Each of the event options has a different set of event inputs. In our case, we just want to create a new record. So we select the kind "Create".
Ditto Tip: Note that you can chain events together in sequences to perform multiple tasks. For example, you could create a record in your database & then add another event to send an email confirming that the record was successfully created.
The options for the create event are split into three sections: General, Event options & Variables.
Under General, you can create a Description for your event.
Under Event options we need to pick the model that we want to insert our new shoe record into. Notice that our new shoe record is available here, because it has been passed on by our endpoint.
The final step is to make sure that the shoes data is mapped into the Shoes data model. This is done by (A) adding properties, (B) picking a property & (C) assigning values to the properties.
The screenshot below shows what the final mapping should look like:
Notice, we do not map either the ID or the Created At properties. This is because these properties are automatically created by the backend system.
Ditto Tip: The ID is an auto incrementing unique identifier for each record added to our data model. The Created At property is the time when the property is created.
The final steps of this setup is to (A) set the "As" variable & (B) press save.
We can now build our code & test it from inside our endpoint.
Building the code for our create endpoint, action & event
When we test the endpoint, the popup become available since we need a place to submit data from.
We have now created:
- 1.An endpoint that receives shoes data & passes the data on to an Action.
- 2.The action receives the shoes data from the endpoint & passes it to the Create event.
- 3.The Create event maps the data into our Shoes Data Model.
The diagram below gives an overview of the entire flow of data from the point of submission, all the way through to the mapping the data into the shoes data model.
If we wanted to allow a third party user to submit data, we would give them the following URL & explain to them that they needed to send a Shoe Type & Price data to it.
Through this Getting Started series we have learnt about Data, APIs, Endpoints, Actions & Events.
The remainder of the "Learn Backend" section is a reference section that explains how to use each of the different combinations of endpoints actions and events. Note, most basic apps can be built using the API Generator, but the reference documents are useful if you're looking to extend the out of the box functionality that Dittofi gives to you.
Last modified 1yr ago