Call a Ruleset via Its API From Postman

Introduction

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.

Optional background: Why are APIs useful?

APIs are useful because they let you implement some functionality once and call it from any software you want. So you don't have to duplicate functionality into each software that needs it. And only have to update the API in case of changes that are instantly available to all software using the API.

As a stepping-stone towards integrating a ruleset API in your software, you're now first going to call a ruleset API from the Postman platform. You can use the Postman platform to call and test APIs to simulate how your software would interact with the API, which includes:

1. Authorizing the API call through an API key, which secures your rulesets.

2. Providing a so-called JSON body as the input to your ruleset.

3. Parsing and processing the returned output, which consists of:

   1. A status code indicating whether the call succeeded or failed.

   2. 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.

Before you begin

• You must have signed up for the Postman platform. You can sign up for free.

Call a ruleset from Postman

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.

Optional background: API status codes

APIs return HTTP status codes such as 404, as you probably know from requesting a web page that doesn't exist. And these are the most common/important codes for APIs:

• 200 (OK)

• 400 (Bad Request)

• 401 (Unauthorized)

• 403 (Forbidden)

• 500 (Server Side Error)

Task: Look up your API key

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:

1. If you're still in your first session, close your web browser to simulate that you finished a session.

2. 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:

   
3. 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.

   With versioning, the longer (two-step) way can be handier. Because over time, you'll have multiple versions of a ruleset, and then the two-step way can be useful because you can jump directly to the right version.

   Either way, Rulecube opens the General settings page of your ruleset, and you can continue from there.

4. 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.

5. Now, click the icon behind the blurred key to copy it to the clipboard.
6. Open a text editor and paste the copied API key into the editor.

Task: Inspect the anatomy of the API call with Swagger.

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:

1. Select Services from the Rulecube menu bar to open the Services page.

2. Open the ruleset for editing.

3. Click Docs.
4. Click the API specification tab, followed by Swagger UI. ↳ Swagger opens a page with the specification of your ruleset API.

5. Click and look around on the page to get familiar with the specification.

Task: Create a JSON body to provide input for your ruleset

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:

1. 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.

2. Click Try it out. ↳ Swagger opens the Execution input field for editing.

3. Select the complete JSON body from the Execution input field and press Ctrl+C to copy the body.

4. Move back to your text editor and paste the body into your editor.

Task: Call your ruleset via its API from Postman

Okay, you've done all the preparation now and are ready to actually call the API from Postman.

1. Navigate to the Postman platform in a new tab in your browser.

2. If needed, log in to Postman.

3. Select Create New. ↳ The Create New pop-up opens.
4. Select HTTP Request. ↳ An Untitled Request page and tab open.

5. Select Authorization from the menu bar.

   
6. In the Type list, select API Key.

7. Move over to your text editor, copy the API key, and switch back to Postman.

8. In the Key field, enter Authorization.

9. In the Value field, paste the API key.

10. If needed, in the Add to list, select Header. ↳ The authorization for the call is set now.

11. Select Body.

12. Move over to your text editor, copy the JSON body, and switch back to Postman.

13. Select raw and paste the JSON body. ↳ The body should look like this:
14. Change the value for Age to 34 in the body. ↳ Your call is ready now to be sent to the API.

15. In the HTTP methods list, select POST.

16. 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.
17. Now, experiment with different body values for Age and inspect the resulting output for DiscountPercentage.

Extra challenge: send an unauthorized call

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.

Recap

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.

What's next?

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.