(Check out the SAP Developer Challenge - APIs blog post for everything you need to know about the challenge to which this task relates!)
In this task you'll learn a bit about actions and functions in OData V4.
Background
While OData V2 did have function imports, the advent of OData V4 brought about enhancements in this area and we now have a clean distinction between different types of orthogonal endpoints that can be presented in an OData service alongside the entity sets, singletons and more. See the Actions and functions sections of the OData V4 and SAP Cloud Application Programming Model talk slides for more info.
With CAP's support for OData V4's actions and functions ready for us to enjoy, it's a good opportunity to try things out here.
In addition to the entity sets we saw in the previous task, the Northbreeze OData V4 service also sports an action. If you check the service's metadata document document you'll see the evidence of this action.
First, it appears alongside the EntitySet elements within the EntityContainer element:
<EntityContainer Name="EntityContainer">
<EntitySet Name="Products" EntityType="Northbreeze.Products">
<NavigationPropertyBinding Path="Category" Target="Categories"/>
<NavigationPropertyBinding Path="Supplier" Target="Suppliers"/>
</EntitySet>
<EntitySet Name="Suppliers" EntityType="Northbreeze.Suppliers">
<NavigationPropertyBinding Path="Products" Target="Products"/>
</EntitySet>
<EntitySet Name="Categories" EntityType="Northbreeze.Categories">
<NavigationPropertyBinding Path="Products" Target="Products"/>
</EntitySet>
<EntitySet Name="Summary_of_Sales_by_Years" EntityType="Northbreeze.Summary_of_Sales_by_Years"/>
<EntitySet Name="TotalProducts" EntityType="Northbreeze.TotalProducts"/>
<ActionImport Name="selectProduct" Action="Northbreeze.selectProduct"/>
</EntityContainer>The action itself is described in more detail along with the EntityType elements. Here it is in full:
<Action Name="selectProduct" IsBound="false">
<Parameter Name="communityid" Type="Edm.String"/>
<ReturnType Type="Edm.String"/>
</Action>
You can see from this detail that:
- it's an unbound action
- it expects a single parameter communityid
- it returns a result
Basically, this action expects to receive your SAP Community ID as input, and, based on that ID, will choose a product for you.
Actions vs functions: One of the key differences between actions and functions in OData V4 is that while functions may not have side effects, actions may well have side effects. This means that normally functions will be used for read-only operations, while actions can be used for operations that make some sort of change. But they don't have to. And here, we're using an action, rather than a function, mostly because actions require the POST HTTP method (because they may have side effects), rather than GET. And requiring you to use HTTP POST for this task makes things more interesting.
Your task
Your task is to call this unbound action, supplying your SAP Community ID for the communityid parameter. The response you will receive is a JSON representation, containing a value property, the value for which is the product that has been selected for you (based on your SAP Community ID).
This is the value you must hash and then post that hash as a new reply to this discussion thread, as described in Task 0 - Learn to share your task results.
Here's an example. Calling the action with qmacro as the value for communityid causes this to be returned in response (pretty printed for readability):
{
"@odata.context": "$metadata#Edm.String",
"value": "Rƶssle Sauerkraut"
}The product name Rƶssle Sauerkraut is what needs to be hashed. Note, in this case, that any value passed in the URL path must be properly URL encoded. So while the value test, for example, needs no specific URL encoding, this value must be URL encoded, in order to be successfully transported in the URL path and accurately received and parsed by the hash service. In other words, the value:
Rƶssle Sauerkraut
needs to be URL encoded so it looks like this:
R%C3%B6ssle%20Sauerkraut
When inserted into the URL path, it will therefore look like this:
/v1/hash(value='R%C3%B6ssle%20Sauerkraut')
Hints and tips
You may want to peruse the content of the talk OData V4 and SAP Cloud Application Programming Model, in particular the short Actions and functions section.
You may also wish to watch the replay of the Hands-on SAP Dev live stream episode Back to basics: OData - the Open Data Protocol - Part 5 - Actions & functions.
You can find out what URL encoding is all about in the Wikipedia entry for URL encoding. You're likely to find either a built-in or a library function in your favorite language to do that, for example JavaScript has encodeURIComponent and Python has a quote function in urllib.parse.
Finally, you may wish to read this short post OData query operations and URL encoding the system query options with curl, written in part as a response to a great comment on the previous task.
For discussion
What's the difference between the meanings of "bound" and "unbound" in this context? What does the fact that the selectProduct action is "unbound" suggest to us?
Remember, if you're posting your thoughts on these discussion questions, remember to do it in a reply separate from your hash reply!
