Task 9 – Using CQL in an unbound action (July Developer Challenge – “Reverse APIs”)

By /

This is a task in the July Developer Challenge – “Reverse APIs”.

In this task you’ll define and implement an unbound action, that does something that you might remember from the Developer Challenge on APIs last year in August, and you’ll end up writing some (hopefully) interesting code for the implementation.

Background

Last year we ran a Developer Challenge on APIs. In one of the tasks – Task 3 – Have a Northbreeze product selected for you – you needed to make a call to an API endpoint supplying your SAP Community ID and it would return a Northwind product. In the example for my ID, “qmacro”, it showed this being returned:

{
  "@odata.context": "$metadata#Edm.String",
  "value": "Rössle Sauerkraut"
}
In other words, the product “corresponding to” my SAP Community ID is “Rössle Sauerkraut”. Different products were returned for different SAP Community IDs, so that your answers would be different to each other. The calculation of which product to return was based on the value of your SAP Community ID.

In this task, you will need to define an API endpoint, in the form of an unbound action, and write the implementation to calculate, look up and return the name of a product that corresponds to the SAP Community ID that is sent by the TESTER.

Correspondence calculation

So how should you determine which product to select for a given SAP Community ID? The same way that it was determined in last year’s Developer Challenge for that task. And that is to turn the SAP Community ID string value into a numeric value, and then use that to select a specific product with an ID (in ProductID) that matches that numeric value.

Here’s the logic:

First:

  • ensure the SAP Community ID is all lower case
  • convert each character to its equivalent decimal ASCII code
  • add the resulting list of ASCII codes together to make a total

Then:

  • determine how many products are in your Northbreeze data
  • read a single product where the key is the ASCII codes total value

Noting that:

  • you will need to use modulo arithmetic to ensure that the ASCII codes total value falls within the range between 1 and the total number of Northbreeze products

And here’s an example of that logic in action, where (for the sake of illustration) the SAP Community ID value “QmacrO” is sent in the payload of the HTTP request:

  • converting “QmacrO” to lower case gives “qmacro”
  • the decimal ASCII codes for “qmacro” are 113, 109, 97, 99, 114 and 111
  • added together, these codes come to 643
  • there are 77 Northbreeze products
  • using modulo arithmetic to turn 643 into a number between 1 and 77, it becomes 28
  • the product with ID 28 is Rössle Sauerkraut

Be careful with the modulo calculation, because you need to take into account that the result of a modulo calculation could be 0, which is not in the ID range. It would also never be 77. This is why 643 modulo 77 becomes 28, not 27 (basically, do the modulo calculation and add 1).

Clearly these instructions have already told you that there are 77 products. You should have 77 products too if you started with the repo as recommended. Nevertheless, we encourage you to use some CQL in your implementation to programatically determine how many products there are, not just set the value 77 in a constant 🙂

The requirements

Here are the specific requirements for this task.

Add an unbound action called selectProduct to the definition of your northbreeze service. It should expect a String value for a single parameter named communityid, and it should return the same type as the ProductName element in the Products entity type.

Note that although you will of course be supplying your SAP Community ID as normal when you submit to the TESTER (see the next section), as usual, it will be the TESTER that picks and sends an SAP Community ID to your endpoint, not you, of course.

In the implementation, use CQL to determine the number of products you have, and then use the logic described in the “Correspondence calculation” section earlier to determine the product ID, based on the (semi-random) SAP Community ID value received. Then use CQL to retrieve that product and return the product name.

Submitting to the TESTER

Now you’re ready to submit your CANDIDATE service, with this new API endpoint, to the TESTER!

The payload

The task identifier you need to supply in the payload of your submission is: northbreeze-selectProduct.

You’ll have already done this sort of thing previously so just head back there for the more detailed instructions if you need them, or to the the section titled “The Tester service, and making a test request” in the main challenge blog post.

You’ll need to submit a JSON payload like this:

{
  "communityid": "<your-community-id>",
  "serviceurl": "<the-URL-of-your-service>",
  "task": "northbreeze-selectProduct"
}
And, just as with the previous (and all further tasks):

  • the value for the communityid property should be your ID on this SAP Community platform (e.g. mine is “qmacro”)

  • the value for the serviceurl property should be the absolute URL (i.e. including the scheme), of your CANDIDATE service which contains the API endpoint (see ℹ️ A note on URLs and services).

That’s it!

Logging of test results

Remember that you can check on your progress, and the progress of your fellow participants – all requests are logged and are available in an entity set served by the TESTER service. The entity set URL is https://developer-challenge-2024-07.cfapps.eu10.hana.ondemand.com/tester/Testlog and being an OData V4 entity set, all the normal OData system query options are available to you for digging into that information.

Until the next task, have fun, and if you have any questions or comments, leave them below!

Scroll to Top