GET Units from HTTP-in

This article is part of the Building Your First API guide and assumes that you’ve already created an HTTP channel.

In this guide, we’ll create an endpoint that returns found unit data in an array. The below is an example of the request used to call the API.

curl --location 'https://example.in.bosbec.io/units' \
--header 'Authorization: 00000000-0000-0000-0000-000000000000'

The returned data will be formatted as below.

[
	{
		"id": "00000000-0000-0000-0000-000000000000"
		"firstname": "John",
		"lastname": "Doe",
		"email": "john@doe.com",
		"phone": "+46700000001"
	},
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"firstname": "Jane",
		"lastname": "Doe",
		"email": "jane@doe.com",
		"phone": "+46700000002"
	}
]

Start off by:

1. Adding an Incoming HTTP trigger
2. Selecting the channel you created.
3. Adding the path “units” to the end of the URL.
4. Selecting the GET method.

Next, add a Unit Pipeline. In the pipeline job, include a “Find units” step followed by a “Save as resource” step. Configure both steps according to the example shown in the image below.

This setup will retrieve up to 99 units from your account and save them to a resource (found_units), which you can then return in the response.

In a more advanced solution, you would likely want to filter these units, either by adding a Filter step or by retrieving units based on specific metadata. However, at this point in the demo, retrieving all units will be sufficient.

Next, we will count the number of units found. If one or more units were found, proceed to a JSON Pipeline where we define what data each object, based on the found units, should contain. This can be done using a Route from meta data job and a .count() function, as seen in the screenshot below.

Now that we have a route checking the number of found units, we may as well add some error handling. If no units were found, we should return a 404 error. Adding a Send API Response job, and dragging a new arrow selecting “Route destination on no match” to it, we can send a response to the API call.

By adding another Send API Response to the main flow, we can now send a 200 OK response with the JSON created in the JSON Pipeline.

The entire workflow now looks like this and will return a JSON with up to 90 units when called!

Adding a query

To search for a specific string, a unit ID for example, we can modify the workflow to look for a query in the request.

Simply replacing the Find Units step with a “Matched unit id” and setting it to {{incoming_http_request.query.id}} would do the trick, searching only for this specific unit ID.

However, it would be beneficial to still be able to get all units from the account when necessary, and get a specific unit when the ID is known.

This can be done by adding another route from meta data job and configuring the route as follows:

1. Metadata source
   • {{defaultvalue( “{{incoming_http_request.query.id}}” || “” )}}
2. Allow empty values in source
   • Checked
3. Compare operator
   • !empty

This ensures that if the ID is not specified in the query, the field will remain empty. If it is, search for all units, but if it is not, search for the ID in the query.

This is what the entire workflow looks like when finished! This can, of course, be modified to search for groups, messages, and other resources and return data in a format as needed. This version of the workflow can also be found in the Workflow Library!