In the real world, you'll apply rulesets by calling their Application Programming Interface (API) to integrate the ruleset into your web application or third-party software. An API is a service that you can call from the web and returns requested data or the result of a calculation. Google Maps, for example, has an API that can return the distance between two places.
As a stepping-stone towards integrating a ruleset API in your software, you're now first going to call a ruleset API from the . You can use the Postman platform to call and test APIs to simulate how your software would interact with the API, which includes:
Authorizing the API call through an API key, which secures your rulesets.
Providing a so-called JSON body as the input to your ruleset.
Parsing and processing the returned output, which consists of:
A status code indicating whether the call succeeded or failed.
The requested data or calculation result.
This might sound a bit intimidating now but don't worry, this tutorial leads you through all aspects, and by the end, you'll know how to:
Look up your API key.
Inspect the anatomy of an API call with Swagger.
Create a JSON body to provide input for your ruleset.
Call a ruleset via its API from Postman.
Inspect the returned output.
Calling a ruleset API takes several steps, and you'll start by looking up your API key. You need this key to authorize your call; otherwise, Rulecube rejects your call and returns a 401 (Unauthorized) status code.
So far, you've worked assuming that you did every step and action from within one session in Rulecube. In practice, this isn't realistic because you end a session and pick up the next day. Rulecube then requires you to open an existing ruleset and work from there. So, let's start with opening an existing ruleset to see how that works:
If you're still in your first session, close your web browser to simulate that you finished a session.
Open your web browser, navigate to your Rulecube link, and log in to start a new session. ↳ Your Dashboard/Services page opens and shows your earlier created ruleset:
Now, you've got two ways to open your ruleset. The quickest one is clicking on the pencil at the end of a ruleset row. For the longer one, click the name of the ruleset to unfold the row and then click the version number.
Either way, Rulecube opens the General settings page of your ruleset, and you can continue from there.
Select <<Your tenant>> from the Rulecube menu bar:
↳ Your Profile page opens and shows a section for API keys like this:
The API key is blurred for security reasons.
Open a text editor and paste the copied API key into the editor.
Swagger is a tool for documenting APIs, and is integrated into Rulecube to let you inspect the anatomy of the API call to your ruleset. Follow these steps to inspect the call:
Select Services from the Rulecube menu bar to open the Services page.
Open the ruleset for editing.
Click the API specification tab, followed by Swagger UI. ↳ Swagger opens a page with the specification of your ruleset API.
Click and look around on the page to get familiar with the specification.
You remember that your ruleset needs input to act upon. And the same goes for the API of your ruleset. Only the API asks for the input to be supplied in JSON format as a so-called JSON body. Here's how you create a JSON body to send along as input when calling your ruleset API:
Unfold the Default execution section and unfold the Post row. ↳ The Execution input – Example Value field shows the basic JSON body for calling your API:
Note the name key with the name of your ruleset and the input segment with the Age key and value 0.
Click Try it out. ↳ Swagger opens the Execution input field for editing.
Select the complete JSON body from the Execution input field and press Ctrl+C to copy the body.
Move back to your text editor and paste the body into your editor.
Okay, you've done all the preparation now and are ready to actually call the API from Postman.
Navigate to the Postman platform in a new tab in your browser.
If needed, log in to Postman.
Select HTTP Request. ↳ An Untitled Request page and tab open.
Select Authorization from the menu bar.
In the Type list, select API Key.
Move over to your text editor, copy the API key, and switch back to Postman.
In the Key field, enter Authorization.
In the Value field, paste the API key.
If needed, in the Add to list, select Header. ↳ The authorization for the call is set now.
Select Body.
Move over to your text editor, copy the JSON body, and switch back to Postman.
Change the value for Age to 34 in the body.
↳ Your call is ready now to be sent to the API.
In the HTTP methods list, select POST.
Now, experiment with different body values for Age and inspect the resulting output for DiscountPercentage.
People learn most when things turn out differently than expected. So, let's make a faulty API call. To do so, change the last digit of your API key and call your ruleset API. Your response should look like this:
This guarantees that only you can access your ruleset APIs.
You've called a ruleset via its API as if you were accessing it in a real-world scenario from external software. So you're already well on your way to mastering Rulecube.
Rulecube is equipped with many predefined and well-tested methods you can use to speed up your ruleset development. So go to the next tutorial to apply methods in your rulesets.
You must have signed up for the Postman platform. You can sign up for .
Now, click the icon behind the blurred key to copy it to the clipboard.
Click Docs.
Select Create New. ↳ The Create New pop-up opens.
Select raw and paste the JSON body. ↳ The body should look like this:
And finally, click Send.
↳ In the bottom section, you'll find the response from the API, which should look like this:
Note the DiscountPercentage key with the value 1.5 as the main output of your ruleset API. Also, note that the status is 200 OK.
