Cheat sheet for URI patterns for calling OData actions and functions

[MioYasutake]

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>&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/v2/catalog/Books_boundFunctionWithParam?ID=1&param1='a'&param2='b'	-
Bound	No	ttp://localhost:4004/v2/catalog/Books_boundFunctionWithoutParam?ID=1	-
Unbound	Yes	http://localhost:4004/v2/catalog/unboundFunctionWithParam?param1='a'&param2='b'	-
Unbound	No	http://localhost:4004/v2/catalog/unboundFunctionWithoutParam	-