Skip to Content
Product Information
Author's profile photo Akshil Verma

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:

  1. 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%201%3A%20Expanding%20API%20Format%20selection%20box

Figure 1: Expanding API Format selection box

 

  1. Choose the appropriate format from the API Format selection box. This change will be reflected as shown in figure 2.

Figure%202%3A%20Select%20a%20specific%20API%20Format%20for%20an%20Action%20Parameter

Figure 2: Select a specific API Format for an Action Parameter

 

  1. Add a value based on the format selected as shown in figure 3.

Figure%203%3A%20Input%20a%20Value%20corresponding%20to%20the%20API%20Format%20selected

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%204%3A%20Behavior%20of%20Input%20and%20Output%20API%20Formats

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%205%3A%20Showcasing%20disabled%20or%20empty%20API%20Format

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

 

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.

 

Assigned Tags

      2 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Karanam Guru
      Karanam Guru

      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

      Author's profile photo Akshil Verma
      Akshil Verma
      Blog Post Author

      Hi Guru,

      Did you try using EDM DateTime ?