Product Information
API Format in Actions Project
Motivation
This blog focusses on the concept and usability of API Formats within an Action of the Actions Project.
Parent Blog
Actions Editor – Feature List, Usage and Maintenance of Actions Project
Concept and Need
Actions Project allows the citizen developer to add a format type to the parameters of the input/output tables. The format can be chosen from the API Format column of these tables. These API formats help to understand the specific data-type format for the parameter that is to be passed to invoke the API.
API Formats are introduced to bridge the gap between the date/time formats that the Action Designer expects and the formats that are internally accepted by the API.
Example:
- Click on the API Format selection box of the specific Action Parameter for which a format needs to be specified as shown in figure 1.
Figure 1: Expanding API Format selection box
- Choose the appropriate format from the API Format selection box. This change will be reflected as shown in figure 2.
Figure 2: Select a specific API Format for an Action Parameter
- Add a value based on the format selected as shown in figure 3.
Figure 3: Input a Value corresponding to the API Format selected
Behavior for Input and Output API Format
When an API format is selected for input parameters, the Action Service will expect a consumer value, and the service will convert them to the specified format types to make the API call.
When an API format is selected for output parameters, the Action Service will convert the response from the selected format type and return the result to the citizen developer in the form of a consumer value.
These behaviors are illustrated in figure 4.
Figure 4: Behavior of Input and Output API Formats
Supported API Format types
As of now, Actions Project supports the following API formats:
| Format Type | Definition | Example value | Consumer value |
| None | No format type is specified. Actions will accept any value for the parameter. | Any value | – |
| DD-MM-YYYY | A date format is specified. |
01-01-9999
|
“9999-01-01” |
| MM-DD-YYYY | A date format is specified. | 01-01-9999 | “9999-01-01” |
| YYYY-MM-DD | A date format is specified. | 9999-01-01 | “9999-01-01” |
| HH:MM:SS | A time format is specified. | 12:34:56 | “12:34:56Z”, “12:34:56+03:00” |
| EDM DateTime | A timestamp format is specified. |
9999-01-01T12:34:56
|
9999-01-01T12:34:56+05 |
| EDM Time | A time format is specified. | PT13H20M55S | “12:34:56Z”, “12:34:56+03:00” |
| EDM DateTimeOffset | A time format is specified. | 9999-01-01T12:34:56Z | 9999-01-01T12:34:56+05 |
| Timestamp since Epoch | A timestamp format is specified. | /Date(1492098664000)/ | 2016-07-08T12:34:56+05 |
| Date since Epoch | A date format is specified. | /Date(1492098664000)/ | “9999-01-01” |
Disabled or Empty API Format
The Action Designer will sometimes encounter a disabled format selection box or would not see the format selection box at all. This is because API formats are not supported for some parameter types.
Figure 5: Showcasing disabled or empty API Format
The following table details the relationship between the parameter type and API format:
| Parameter Type | API Format |
| string | Supported. Format selection box is shown and usable. |
| integer | Not supported. Format selection box is shown but disabled. |
| boolean | Not supported. Format selection box is shown but disabled. |
| number | Not supported. Format selection box is shown but disabled. |
| array | Not supported. Format selection box is not shown. |
| object | Not supported. Format selection box is not shown. |
Blog Reference
- Part 1 of the Blog Series: Actions Project – Major Changes including the Actions Editor Available Now !!
- Part 2 of the Blog Series/Parent Blog: Actions Editor – Feature List, Usage and Maintenance of Actions Project
Thanks for reading and I hope it helped to understand the concept of API Formats in Actions Project. Please feel free to leave a comment if there are any questions and I would be happy to receive any feedback.
Hi Akshil
The user enters the date in the form using the short format "DD.MM.YY" now the API in the action expects the date in YYYY-MM-DDTHH:MM:SS so in this case how should we convert the user entered date in form to the target format as API expects in the action editor
I tried many ways, but was unable to map the date field in the form to the input field in API related to the date, the mapping is diasbled.
Can you advise if there is a way out here.
With Best Regards
Guru
Hi Guru,
Did you try using EDM DateTime ?
Hi Akshil,
I case of get call, I am using custom odata get_expanded_entityset method to get the Header and Item details (Deep Entity). May I know How to achieve below URL because when I use $filter as query, it automatically adds "?" and becomes "?$filter". But if you look at the URL, I need &$filter to get the data from backend. plese guide.
Hi Digant,
Thanks for the question.
In custom odata get_expanded_entityset method, are you trying to apply the filter on the header element (GetXXXXHeaderSet) or on the child element (GXXXX)?
Hi Akshil,
I am trying to apply filter on the header element (GetXXXXHeaderSet).
Regards,
Digant Trivedi