Technical Articles
Cheat sheet for URI patterns for calling OData actions and functions
When developing CAP services, I often stumble upon testing actions and functions, because URI patterns vary depending on action / function, if it is bound or unbound, and OData version. That’s why I decided to write this short blog post for my reference. I hope this also helps someone else.
To test the examples below, clone the following GitHub repository and run cds watch.
https://github.com/miyasuta/actions-and-functions
*Actions cannot be tested form the browser. Use tools such as Postman or REST Client (VS Code extension) and send a POST request.
To learn more about CAP actions and functions, and what are bound / unbound actions / functions, please find the document below.
https://cap.cloud.sap/docs/cds/cdl#actions
OData V4
Actions
General patterns
- Bound Action:
pathToService/EntitySet(key)/ServiceName.actionName - Unbound Action:
pathToService/actionName
Examples
Note that you need the header content-type: application/json, even if the action doesn’t require parameters.
| Bound / Unbound | Has parameters | Example URI | Example Body |
|---|---|---|---|
| Bound | Yes | http://localhost:4004/catalog/Books(1)/CatalogService.boundActionWithParam | { “param1”: “a”, “param2”: “b” } |
| Bound | No | http://localhost:4004/catalog/Books(1)/CatalogService.boundActionWithoutParam | – |
| Unbound | Yes | http://localhost:4004/catalog/unboundActionWithParam | { “param1”: “a”, “param2”: “b” } |
| Unbound | No | http://localhost:4004/catalog/unboundActionWithoutParam | – |
Functions
General patterns
Parenthesis() are required after function names.
- Bound function:
pathToService/EntitySet(key)/ServiceName.functionName(paramName1=<value>,paramName2=<value>) - Unbound function:
pathToService/functionName(paramName1=<value>,paramName2=<value>)
Examples
| Bound / Unbound | Has parameters | Example URI | Example Body |
|---|---|---|---|
| Bound | Yes | http://localhost:4004/catalog/Books(1)/CatalogService.boundFunctionWithParam(param1=’a’,param2=’b’) | – |
| Bound | No | http://localhost:4004/catalog/Books(1)/CatalogService.boundFunctionWithoutParam() | – |
| Unbound | Yes | http://localhost:4004/catalog/unboundFunctionWithParam(param1=’a’,param2=’b’) | – |
| Unbound | No | http://localhost:4004/catalog/unboundFunctionWithoutParam() | – |
OData V2
Actions
General patterns
Two URI patterns are accepted for bound actions. Pattern1 is the same as v4, and pattern2 is specific to v2.
- Bound Action (pattern1):
pathToService/EntitySet(key)/ServiceName.actionName - Bound Action (pattern2):
pathToService/EntitySet_actionName?key=<value> - Unbound Action:
pathToService/actionName
Examples
Note that you need the header content-type: application/json, even if the action doesn’t require parameters.
| Bound / Unbound | Has parameters | Example URI | Example Body |
|---|---|---|---|
| Bound | Yes | http://localhost:4004/v2/catalog/Books(1)/CatalogService.boundActionWithParam | { “param1”: “a”, “param2”: “b” } |
| http://localhost:4004/v2/catalog/Books_boundActionWithParam?ID=1 | { “param1”: “a”, “param2”: “b” } | ||
| Bound | No | http://localhost:4004/v2/catalog/Books(1)/CatalogService.boundActionWithoutParam | – |
| http://localhost:4004/v2/catalog/Books_boundActionWithoutParam?ID=1 | – | ||
| Unbound | Yes | http://localhost:4004/v2/catalog/unboundActionWithParam | { “param1”: “a”, “param2”: “b” } |
| Unbound | No | http://localhost:4004/v2/catalog/unboundActionWithoutParam | – |
Functions
General patterns
OData V2 functions work with or without parenthesis() after function names.
- Bound function:
pathToService/EntitySet_functionName?key=<value>¶mName1=<value>¶mName2=<value> - Unbound function:
pathToService/functionName?paramName1=<value>¶mName2=<value>
Examples
| Bound / Unbound | Has parameters | Example URI | Example Body |
|---|---|---|---|
| Bound | Yes | http://localhost:4004/v2/catalog/Books_boundFunctionWithParam?ID=1¶m1=’a’¶m2=’b’ | – |
| Bound | No | ttp://localhost:4004/v2/catalog/Books_boundFunctionWithoutParam?ID=1 | – |
| Unbound | Yes | http://localhost:4004/v2/catalog/unboundFunctionWithParam?param1=’a’¶m2=’b’ | – |
| Unbound | No | http://localhost:4004/v2/catalog/unboundFunctionWithoutParam | – |
Useful! Thanks Mio
Nice Mio, thank you. It helped me a lot!