The Apply Query Parameter object is used to filter and sort data in an API flow in accordance with the user application. Its location in an API flow can depend on when sorting or filtering is required in the processing of the API request.

Configuring the Apply Query Parameter object

1. To start, right-click on the object and select Properties from the context menu.

The layout builder window will open.

This is where the layout of the incoming data is going to be mapped. It can be automatically mapped from a preceding object.

For our use case, we have a flow that fetches order items from the database for the given OrderID in the request. Now, to allow sorting and filter operations on this response data, we will add the Apply Query Parameter object right after the Database Lookup object and before the Response object.

The position of this object in a flow can depend on where it is required. It can be placed anywhere between objects in the API flow.

Thus, our layout builder is populated according to our flow.

2. Once done, click Next. Here, you can enable filter and sort functions on the API response data.

Apply Filter Parameters: This allows users to send filter parameters of response layout fields in the request URL.

Apply Sort Parameters: This allows users to send sort_by parameter of response layout fields in the request URL.

3. Select Ok after you are done with this window and the configuration will be completed.

The Apply Query Parameter object has been configured to return responses as per the sort or filter parameters requested.

Applying Filter and Sort Parameters in Request

1. To further examine filter and sort functionalities, deploy the flow you have used the Apply Query Parameter object in.

2. To deploy the API flow, select the third option from the right, on the designer toolbar.

This will open a new screen,

3. Provide the Deployment Name and the Config File Path, if any, and click Ok.

Generate Test Flow for API: Selecting this option will generate a flow to execute a test request for the API in run-time, to use after deployment.

4. Once done, you can open the generated test flow from the job progress window.

5. Right-click on the API Client object and select Properties from the context menu.

6. Click Next and you will be led to the Parameters screen.

Here, you can use the sort_by parameter or the filter parameters, with the appropriate syntax, to obtain accurate data.

To sort the response data, we can define the query parameter ‘sort_by’. This parameter takes comma-separated values for multiple fields that need to be sorted. The syntax for each sort is as follows:

FieldName - SortOrder - Where the sort order can either be asc for ascending or desc for descending.

For example, a sort value as UnitPrice-asc, ProductName-desc would first sort the data by Unit Price in ascending order, then apply a second sort by Product Name in descending order.

FieldName [Operator] - To add a filter on any of the response fields, you can define a query parameter with this syntax. The supported operators include,

• Equals to – eq

• Not equal to – neq

• Greater than – gt

• Greater than or equals to – gte

• Less than – lt

• Less than or equals to - lte

For example, to apply a filter on discount, we have defined a query parameter Discount[gt] as the parameter key and 5 as the value for this filter, implying to only show discount records greater than 5 in the response data. Additionally, more such filter parameters can also be added for other response fields.

7. Click OK.

The parameters have been added.

8. Next, right-click on the API Client object and select Preview Output to make an API call with the defined parameters.

The status code ‘200’ shows that the API call was made successfully.

This concludes the usage of the Apply Query Parameter object after deployment, within a test flow.

Video

What is an API Flow?

An API flow is an artifact to design a data or a function service endpoint incorporating various data connectors, transformations, quality checks, task-based operations, integrating services, and much more. It defines an end-to-end flow for processing an input, applying transformations and integrations, and routing to response definitions.

Astera Data Stack holds the ability to create an API Flow as an API endpoint by defining its request and response objects with in-built abilities to apply sort, filter, pagination, and error handling on responses.

Creating an API Flow

Let’s see how we can create API flows contained in a project:

1. To create an API Flow, navigate to the main toolbar, select Project, and click on it. Then, hover over New and select Integration Project.

2. Once the project is created, head to the Project Explorer. Right-click on any of the folders in the project and hover over Data Services. Then select Add New API.

By default, your API Flow file will contain the two required objects, Request, and Response, which act as start and stop objects for an API flow. This flow will be saved with a .API extension.

Configuring the Request Object

The Request object is used to define the request endpoint resource, input parameters, and message payloads expected from the API user which would then be used in the flow processing.

1. To start, right-click on the object and select Properties from the context menu.

Once done, the parameter configuration window will open.

Here, you can define all the expected parameters from the request. To define a parameter, specify a name, location, and the data type.

Name: To define the name of the parameter.

Parameter Location: Here, the location of the parameter is selected between either URI, Query, or Header.

Data Type: To define the parameter’s data type expected from the request. Sending an incorrect data type would result in a 400 BadRequest error response.

Default Value: Add a default value, if any, to be used for optional query or header parameters when the incoming request is missing these parameters.

Parameter Description: These will be used in the auto-generated Open API Swagger specification.

Required: This checkbox is selected if the parameter must be included for a request to be valid. The API returns a 400-Bad Request error response if required parameters are not provided.

2. Once done, select Next, and the API Configuration screen will appear.

HTTP Configuration for Request Object

HTTP Method: There are five methods based on which the request object can be configured. The method depends on the resource operation happening in the flow. These options are,

1. Get: Used when the flow is fetching data from a resource based on the given request parameters.

2. Delete: Used when the flow deletes an object based on the given request parameters.

3. Post: Used to create a new object resource. In addition to request parameters, the POST method also allows a request payload which can be defined as the input layout.

4. Put: Used to update an existing resource. It also allows input parameters and a payload in the request definition.

5. Patch: This method qualifies to partially update an existing resource. It also allows input parameters and a payload in the request definition.

Resource: The resource entity for the API operation. It becomes part of the request URL. Here, since we are designing an API to read order items, we will call our resource “OrderItems”.

Example URL: It displays the complete request URL formed with the appended resource and parameters.

Content Type: The format of the content we are sending within the request.

When selecting the HTTP method other than Get, there are a few content types that Astera Data Stack Supports:

• application/json

• multipart/form-data

• application/x-www-form-urlencoded

• GraphQL

Published Description: A description for the API operation on the given resource. You could use the default generated description or modify it to your own description. This description for the API endpoint will be used in the auto-generated Open API Swagger specification.

Show Advanced Fields: Enabling this will display additional information fields in the requestinfo node. These include information about the incoming request that can be further used in the API flow, such as connection, local address, local port, IP Address, etc.

Show User Context Fields: Enabling this will display user profile fields from the incoming request in the requestinfo node. These fields show information such as username, email address, whether the user is locked out or not, etc.

Synchronous: API request executes synchronously such that an API call blocks and returns to the client only when a response from the server is ready.

Asynchronous: To deploy the API as an asynchronous operation. This implies that the requestee does not need to wait for the response to be processed. On making a request, the server responds with a 202 Accepted message and starts to process. The client can periodically check the status and read the response when available.

Create Unique Files for Uploads: When uploading a file with the multi-part content-type, selecting this option will create a new file every time the request is run.

To learn more about Synchronous and Asynchronous, click here.

3. For our use case, we are using the Get method to find order items by ‘OrderID’.

3. Click OK, and your request object will be configured using the Get method.

As you can see above, the object has been configured by our requirements.

This concludes the configuration of the Request object in Astera.

Configuring The Response Object

An API endpoint flow begins with a request object and ends at one of the many responses defined as per the flow execution route.

1. To start, right-click on the object and select Properties from the context menu.

Then, the response configuration window will open, where you can specify the HTTP status code to be returned.

HTTP Status Code: API response will be based on this selection of the HTTP status code and the API flow orchestration designed. These codes can be designed based on successful runs or errors etc.

To learn more about multiple responses in an API flow, click here.

Mapped Content Layout: Selecting this option allows you to map a pre-serialized response string and its content type as input to the response object.

Custom Layout: Selecting this will allow you to build a layout for the response on the next screen based on the content type defined.

Content Type: You can select a standard media type for the response payload and define its custom layout on the next screen. The following ones are supported,

Published Description: This description becomes a part of the auto-generated open API definition.

2. Once done, click Next and you will be taken to the next screen.

Here, the output layout of the response object can be defined.

On the left side of the screen is the hierarchy of the nodes in your layout. You can add or delete a single instance or collection members here to create the desired layout.

The right side of the screen is where the layout is to be added. There are three ways to map the output layout,

• Manually defining objects and fields,

• Using a sample text.

Selecting this option will open a new window where a sample text, based on the Content-type defined, is given to generate the layout accordingly.

Clicking this will open a new sample text window where the text can be pasted.

Clicking Generate will produce a layout.

• Generate default layout

Selecting this option will generate a default Astera layout which can be used to output an error and any additional messages.

As we click on this option, the box is populated.

3. Once done, click Next and you will be led to the Output Parameters screen.

Here, you can define header parameters to be returned as part of the response.

4. Click Next when done and you will be led to the Pagination screen.

The pagination screen allows you to set a form of pagination on the Response data. You can configure Cursor Pagination for 200 OK responses to retrieve ordered data in small discrete sets, as requested. The first request returns the records as per Page Size and a cursor field which can then be iteratively used to read the next set of records.

To learn more about pagination, click here.

Enable Cursor Pagination: Selecting this is going to enable Cursor Pagination on the data payload returned.

Page Size: This determines the size of a page in cursor pagination.

5. Once that has been done, select Next and you will be led to the General Options screen.

6. Click OK and the Response object will be configured. You can now map the fields and parameters from the flow to the response object.

Body: This node will show the output layout hierarchy that has been configured within the properties.

Responseinfo: Upon expansion, this node will display additional information that can be mapped to an output to be processed further in the test-flow, after the API response has been submitted.

Headers: Expanding this node will show any headers that have been defined within the object.

This concludes the Response object configuration in Astera.

Using the Request and Response objects in a flow

Since we have now configured the Request and Response objects, we can map them together and use them in a flow. The API flow feeds the input Order ID to a database lookup and returns the output in the response.

The following is a use case built on ‘Order_Details’ data.

This concludes using the designing of an API flow.

In the Astera Data Stack, we can process an API request either synchronously or asynchronously.

In Synchronous execution, the response to the API call does not return until the process has been completed or there has been an error.

In Asynchronous execution, the response to the API call is returned immediately with a polling URL while the request continues to be processed.

To check the functionality of such execution, we have created an API flow that will process the request Asynchronously.

Processing an API Request Asynchronously

For our use case, we are deploying an API flow, which calls another 3rd party API and may take long to respond.

1. To enable Asynchronous execution, right-click on the Request object and select Properties from the context menu.

This will open the Properties window.

2. Click Next and you will be led to the API Configuration screen.

By default, the synchronous option has been selected,

After we select the Asynchronous checkbox, the API controller path in the Example URL also changes to ‘publishingAsync’.

If we plan to deploy both processing types, the Example URL just shows the Synchronous API example,

3. Click OK and deploy this flow through the option present in the API flow toolbar.

This will open a new window where the deployment name can be defined.

4. Once the deployment has been created, you can view it in the Server Browser.

As you can see, the GET endpoint icon here represents Asynchronous processing,

If we had selected both processing types, the endpoints would have looked like this,

To show each of the steps associated with Asynchronous API requests, we will be using the Postman API Client to execute a request on the deployed Astera API.

5. Open your Postman Client, create a new collection, and add a new request to it.

We have named our first request as ‘Async’.

6. Select the appropriate method and enter the API URL copied from the API Browser,

We can see the respective Postman request below,

7. Click Send.

It shows us that the request was accepted.

We have received a location response header and this parameter contains the successive status API’s URL that can be used to inspect the API request’s processing status.

8. Next, send a follow-up request to the status API URL received in the location header.

9. Click Send and you will be able to view the status of the API call in the response body.

‘Status: Completed’ means that the request we sent was completed.

Apart from this, the other status possibilities are,

Running: The request is still being processed.

Error: The request processing has encountered an error.

Unknown: The request for the given ID was not found or purged.

10. The location response header received with a ‘Completed’ status API call is then used to make the successive API call to retrieve the API results.

11. Make a request to this result API to see the actual API response processed.

The result of an Asynchronous request is preserved for 24 hours after which it is purged/removed.

As you can see, after 24 hours, the status becomes ‘Unknown’ and the Status/Result APIs return a ‘404 Not Found’ response.

Callback URL

Attaching a Callback URL in an Async request allows the API client to get the response at the server specified in the URL, rather than polling for a response at various intervals.

The Callback URL’s functionality is implemented for the Asynchronous API Requests. A query parameter called callbackUrl defining the URL of the listening server is required in the Asynchronous request. Once the request is sent to the Astera server, it stores this call-back URL and periodically checks for the availability of the response. When the status is “completed” i.e., when the response is available, the Server sends it to the address that was specified in the URL.

The visual representation of the process will look like this,

1. Callback URL to the Listening Server,

2. Callback URL to the Local Host,

Let us consider such a use-case in which a callback URL query parameter with the value “http::” is defined in the Asynchronous request.

It is necessary to encode the callback URL. After that, the request will look something like this,

Once the request is sent, the Astera server checks if the Status of the request is completed or not, and when it is, the response is sent, and it can be seen at the specified destination address.

Now, the returned Result API’s URL in the Location header parameter can be used to retrieve the response body of the initial Asynchronous call.

This concludes the article on Asynchronous API Request Execution and Callback URL with respect to Astera.

Video

Users can auto-generate CRUD API endpoints for any database using the Data Source Browser. CRUD APIs are meant for Create-Retrieve-Update-Delete operations on the database table records.

1. Click on View in the main menu bar and select Data Source Browser from the drop-down menu.

This will open the Data Source Browser.

2. Add a new database server by selecting the Add Database Server option.

This will open a configuration window to define a database connection. A database server can be configured from any of the listed providers.

3. Add all the essential details to configure the database server connection and click OK.

Now, the Data Source Browser will be populated with all the databases from the connected server.

4. Right-click on any database and select Generate CRUD flows from the context menu.

This will open a new window.

Here, you can select the tables and the respective CRUD operations to generate API flows.

For our use case, we will be selecting the Orders table. The following operations are available for each table:

1. Find all records – A Get method that fetches all the records

2. Get record by ID – A Get method along with a path parameter for a key that fetches the records based on the key.

3. Create a new record – Selecting this creates a new record.

4. Update a record by ID – Selecting this option lets the user update a record by ID

5. Delete a record by ID – Selecting this option lets the user delete a record by ID.

The user can even select configurations inside each endpoint, whether they want to enable sort or filter, or whether their execution type is Synchronous or Asynchronous.

5. Once done, click Generate and the CRUD flows will be generated.

You can then view the API endpoints in the Project Explorer.

6. Now, you can directly group and deploy with a single click,

or open any of the API flows to see pre-configured API flows or make any changes.

This concludes the working of the Database APIs CRUD auto-generation in Astera.

Video

An API flow orchestration allows the usage of various workflow tasks. These include tasks like Send Mail, System File Actions, Run Exe Programs, Run Flow tasks, FTP tasks, etc, which can be utilized per the API action.

Inside the toolbox, the Workflow Tasks tab lists all the available tasks that can be used when designing an API flow.

For our use case, we have designed an API flow for the ‘Get Product by name’ endpoint.

As you can see in the flow above, two Send Mail workflow tasks have been used. Once a request is received with the product name, it is sent as input to the Database Lookup object to fetch a matching record. It is then passed through a Route Transformation which routes the data to send a confirmation mail for a successful match or a ‘Not Found’ mail notification otherwise.

The user will either receive a mail that says the item is available or a mail that states that the item is unavailable, and the API will return the respective responses.

To learn more about how Anchor Maps are used, please refer to the respective document here.

Similarly, here is another way we have used workflow tasks within an API flow,

Instead of using the DB Lookup and Route Transformation object, the entire process has been replaced with a Run Dataflow object that can run any ETL pipeline.

The dataflow that will be triggered in the API is doing the same work as the previous API flow. However, it is now less cluttered.

This concludes the functionality of Workflow tasks in an API flow.

Video

Instant Data Preview

When designing an API flow, users can benefit from the functionality to instantly preview and verify the input and output data for any action in the flow. Carrying out data-driven testing of the API functionality at design time helps identify any possible hindrances sooner.

To define test values for the API flow, the Request object must be set as a transformation and any test data can be mapped to it. Right-click on the Request object and select Transformation.

Since the request object is a Singleton object, only the first record is processed through the flow. This behavior compliments the runtime behavior of a single API call and provides ease in previewing the respective results. Let’s preview the Request object to observe this.

Raw Request/Response Preview

The Preview Raw option alternatively allows the users to view the API request and response in a raw unformatted form. This option is useful as it not only displays the data as a raw HTTPS packet but also gives us the benefit of copying, saving, or sharing the JSON body of both the request and response.

Let’s take an example API flow and see how we can preview the raw request in Astera,

This API flow uses the GET HTTPS Method and allows the API user to view the Customers table’s records based on the value of the URI parameter username. For demonstration, Header parameters i.e., Accept, UserAgent, Query parameter i.e., cursor, and RequestInfo parameters i.e., HTTPMethod, Content-Type are also defined.

1. The Raw Data Preview window will automatically open when a raw request/response is previewed. However, we can manually open the window as well. To do that, go to the Menu bar > View > Raw Data Preview or use the shortcut Ctrl+Alt+J.

2. Right-click on the header of the Request Publish object. Select the Preview Raw Request option from the context menu.

In a raw API Request, you can see:

• URL: Contains the HTTPS Method, Resource, URI, and Query parameters.

• Host: The server on which the API is deployed.

• RequestInfo: Default parameters containing information related to the server and request.

• Header: User-defined parameters containing meta-data associated with the request.

• Body: In case of a request other than GET, an input JSON body.

This is how a complete request looks in the Raw Data Preview window,

The RequestInfo, Parameters, and JSON Body are displayed in separate tabs.

In case of a request other than GET, we’ll be able to see the Input JSON Body in the Body tab. Similar to this:

In a raw API response, you can see:

• Date: It specifies the date and time at which the client receives the response.

• HTTPS Status Code: It defines the standard response status expected from the executed flow i.e., 200 for OK or 400 Bad Request, etc.

• HTTPS Status Description: The standard response description matching the HTTPS Status code i.e., OK for a 200 code or BAD REQUEST for a 400 code, etc.

• Header Parameters: User-defined parameters containing meta-data associated with the response.

• Content: It contains the whole response body content in a string-like text.

• Content-Type: It describes the format type of the response body content.

• Content-Length: It specifies the number of bytes in the content of the response body.

• Body: It shows the response content parsed as per a defined Custom Response Layout.

Let’s see how we can preview the raw response in Astera,

1. Right-click on the header of the Response Publish object. Select the Preview Raw Response option from the context menu.

This is how the whole response looks in the Raw Data Preview,

Similarly, the RequestInfo, Header Parameters, and JSON Body are displayed in separate tabs.

Save/Copy JSON

Using the Preview Raw Response/Response option, it is also possible to copy and save the JSON body of both the request and response.

1. Click on the Copy JSON Body icon in the Raw Data Preview window.

2. Similarly, click on the Save JSON Body icon to save the JSON body at the desired destination in a JSON format file.

Enter the desired destination in the Save JSON Body window and click Save to store the file.

This is what the save JSON file looks like,

Flow Verification

If the API flow contains any errors or warnings that affect the flow of data, they are displayed in the Raw/Data Preview window. In other words, if any obstacles block the flow of data from the Request to Response, the error is shown prominently on the window.

For example, we can see that the flow of data has been broken between the Request and Database Source object, resulting in an error state i.e., the Route is unable to identify a parameter, and as we preview the object we can see the error message in the window.

As for the whole API flow’s verification, it is advised to use the Verify Pushdown Job option. To learn more about pushdown verification in API flows, click here.

This concludes our discussion on pre-deployment testing and verification of API flows.

Video

Request Context Parameters allow us to use Request Parameters anywhere within the scope of the API flow. They can be used at any point within the flow following the Request object.

For our use case, we will look at the parameters defined in our flow.

1. Right-click on the Request object and select Properties from the context menu.

This will open a new window.

As you can see in the image above, we have defined a query parameter. This can be directly used as a variable further in the API flow to design the flow logic and set values.

Following the request object, the flow uses a SQL Query Source object to read all products where the category name matches the request parameter value. Since a SQL Query Source requires a SQL query to be defined, let’s see how we can use the incoming query parameter in the context of the SQL query.

These Context Parameters can also be used in other objects as variables. As another example, we have used them to define expressions.

2. We will open the Properties of the Expression object.

This will open the configuration window for the object.

3. Click on a field and open the Expression Builder. Here, all request parameters are available and can be referenced to be used in expression functions.

Here, you can see that we have defined Request Context Parameters using the values we had in the Request object.

These parameters can be used anywhere in the entire API flow.

This concludes the working of the Request Context Parameters in Astera Data Stack.

Users can utilize APIs to upload and download files to and from the Astera server.

1. Head to the Server Explorer, right-click on the cluster node and select Server Profiles from the context menu.

This will open a new window.

2. Create a new profile by clicking on the following icon,

3. Once the new profile is created, select the Publishing Settings tab,

4. Go to the API File Server Configuration section. Here, we can configure the file action functionalities.

Enable File Uploads: Selecting this checkbox will let the user upload files onto the specified server directory.

Enable File Downloads: Selecting this checkbox will let the user download files from the server.

File Expiration Time: This counter determines how long the file will be kept in the Server File Directory before it is automatically removed.

Server File Directory: This is where the file path will be given to the Server File Directory. All the file uploads will be saved here, which can also be downloaded.

5. Select both checkboxes and provide a file path.

6. Once done, save the changes to the server profile.

7. Next, right-click on the Server URL node in the Server Explorer and select Server Properties from the context menu.

This will open the Server Properties window.

8. Select the Profile that you have just configured and save it.

File upload and download functionalities have now been enabled with this profile on the server.

Enable Download-Upload for Non-Admin/Non-Root Users

For a non-admin or a non-root user, we must go to the user roles and enable the Upload Download File APIs option, otherwise, the user cannot proceed with the upload document.

1. Right-click on a non-root role and select Edit Role Resources from the context menu,

This will open a new window.

2. Expand the Url node and select the files node under API to enable download-upload,

Uploading a File

For our use case, we will be using the Postman API Client from another remote machine.

1. Add a new request to your Postman collection by right-clicking on the collection and selecting Add Request from the context menu.

2. Select the HTTP method as POST, provide the file API URL deployed at the Astera Server, and define a multipart/form-date request body,

“HTTPS://ServerHostName:9263/api/files”

3. Define a Key of your choice and select its value type as File,

4. Browse your desired file to the VALUE,

5. Click Send and the file will be uploaded to the specified file directory on the Astera Server.

As seen from the response above, the respective file has been uploaded.

The FileName is the key defined whereas the path is the relative path of the uploaded file on the Astera Server.

This allows the user to define custom values and overwrite predefined values from Astera. ‘TimeToLive’ refers to the time that the file is kept before it expires. ‘AccessPermission’ defines who has access permission other than the user.

Downloading a File

1. To download a file from the server, create a new request on Postman.

For our use case, we will be downloading the same file that we previously uploaded to the server.

2. Keep the HTTP method as GET and enter the request URL.

“HTTPS://ServerHostName:9263/api/files/{filepath}”

We are using the same file upload API resource as GET for the download function. However, the difference is that we provide the relative path of the uploaded file as a resource.

3. For the server to identify the relative file from the request URL, we need to encode the value.

4. Click Send and the request will fetch the file’s content in the response body.

5. The response can then be saved to a file using the following option,

This is how a file can be downloaded from the Astera server.

Generating Downloadable path for files through Astera

Astera offers the user the ability to generate the downloadable path for any destination file using the Download Path Generator object.

This functionality can be seen within the scope of an API flow.

For our use case, we have the following API flow,

In the above flow, we can see that a file path has been given to an API Request object through a Variables object. We are trying to consume the uploaded file here using its relative path.

The flow then maps the request object to an Excel Source object, used as a transformation, and writes the records to a Delimited Destination object.

The Delimited Destination object has an additional File node. This enables us to create a new destination file on each run. Each file is created by appending a unique ID to the destination path given in the object, eliminating the chances of overwriting an existing file. This FilePath field outputs the unique path generated at runtime.

This can be enabled for any destination object.

1. Right-click on the Delimited Destination and select Properties. Next, check the Create new file on each run option. This will add the unique file path node to the destination object.

2. Drag-and-drop a Download Path Generator object from the toolbox onto the API flow.

For us to obtain a downloadable path for our file, we require the use of this object.

3. Map the input using the File Path field from the Delimited Destination object and map the output towards the API Response object.

This downloadable file path can now be used in further applications where the file is required.

Below, we can see the request being sent from Postman and the user receiving the downloadable path in the response.

This concludes our document on enabling and using file download/upload in Astera.

Video

You can configure an API flow to paginate response data from the Response object.

Pagination is a process that is used to divide large data into smaller discrete pages, thus allowing for less clutter and better readability. It also means that server request processing will be faster as a small subset is to be returned. Hence, improving the overall API performance and readability.

For our use case, we have an API flow that is configured to retrieve a collection of order items using a database lookup along with filter and sort functionalities enabled. Now, let us see how pagination can be configured in this flow.

1. Right-click on the Response object and select Properties from the context menu.

This will open the Properties window.

2. Click Next until you reach the Response Configuration window.

This is where you can set up pagination options to better structure the response data fetched for a successful 200-OK request.

Enable Cursor Pagination: Checking this box lets the incoming data be paginated by a cursor. Cursor-based pagination works by returning a pointer to the last item in the dataset page, using which the client can make successive requests to read the next set of records iteratively. Once all records have been read, the cursor value becomes null, thus indicating that no more records are left to be read.

Page Size: This counter determines the number of records returned in a single requested page.

3. Click OK and the Response object will be configured in accordance with the cursor pagination and page size.

At runtime, these paginated calls are cached on the server. To learn more about it, click here.

Video

An API flow can be conditioned to return a different response as per the designed flow. The server could return a successful response for a valid request or return a missing parameter response for an incomplete request.

To define an API with multiple responses, we have mapped two Response objects through a Route Transformation object conditioned on the request received. The Route conditions should be defined to take care of routing all the incoming data to either of the two responses at a time, avoiding any unexpected responses due to race conditions.

Since no data is flowing for a ‘No Content’ response, such responses can be controlled using Anchor Maps. These are mapped with the Route Transformation outgoing node for the respective rule.

To create an anchor map, press the icon on the API flow toolbar and create a map from the UnderProcess rule node of the Route Transformation to the ‘Resp_200_02’ Response object.

This concludes the working of multiple responses in an API flow.

Astera lets the user view their API deployments in a Swagger UI from the deployment section of the Server Browser.

For our use case, we already have deployments created, as evident in the Server Browser panel:

1. To view the swagger options, right-click on the deployment node and hover over Swagger Options.

2. Selecting View Swagger UI is going to present us with a new window where we can see Swagger for our deployed APIs.

The user can authorize, test, copy the response layout, and do a lot more within this UI.

You can expand each endpoint to view its details and you can also provide authorization for when consuming these endpoints.

This concludes working with the Swagger UI feature in Astera.

Video

Generating a Test Flow

The Generate Test Flow option auto creates post-deployment test flows. These dataflows can be used to make live requests to the deployed API endpoints using the API Client and API Connection objects.

The API Connection object contains the base URL of the server where the APIs are deployed and is configured with an Access Token for Authentication.

The API Client object encapsulates the entire API flow’s logic, starting from the Request object to the Response Publish object, including request parameters, request and response content bodies, and pagination configurations.

Other objects that are mapped either to the Request object or from the Response object will not be encapsulated in the API deployment and shall remain as it is in the test flow generated.

However, any Workflow Tasks shall not be made part of the test flow.

Flow Level

Generate Test Flow Icon

At the flow level, use the Generate Test Flow icon in the API flow toolbar to create the test flow for a deployed API.

Check the Job Progress to see if the test case generation resulted in a failure or success. Here, it is successful. This is the generated test flow for the API.

You can run this test dataflow to check the behavior and assess the performance and functionality of the designed API.

Generate Test Flow for API checkbox

At the flow level, we can also check the Generate Test Flow for API checkbox on the deployment window.

This creates the test flow after the creation of the deployment. However, only when the API flow’s verification is successful, the test flow is created. Otherwise, the entire process results in an error.

Folder Level

Generate Test Flows for grouped APIs checkbox

For the Folder level test flow generation, check the Generate Test Flows for Grouped APIs check box while deploying the APIs.

Check the Job Progress to see if the verification of the API flows and the test case generation resulted in a failure or success along with the deployment creation job traces. Here, the test flow creation was successful.

Verification of the API Flows

If the API deployment contains any errors or warnings, the deployment process is terminated with a link provided in the Job Progress window.

Clicking on this View Verification Logs link opens the Verify window. Here, we can see the verification logs. Its shows the Severity i.e., Error or Warning, the Name of the object which contains the issue, and the Message which is the description of the error/warning.

Generating Test Flow from the Server Browser

Astera Data Stack also lets the user generate a test flow from the Server browser.

For our use case, we have an API flow that reads data from a sample Northwind database and sends it in the API response.

1. Deploy the API flow.

2. Click OK and you will be able to see the deployment in the Server Browser.

For all Endpoints

To generate test flows for all endpoints present within a deployment, right-click on the deployment file and select Generate Test Flows for All Endpoints.

For each Endpoint

To generate a test flow for a specific endpoint, open the deployment to view endpoints, then right-click on the desired endpoint and select Generate Test Flow.

Selecting it will generate the respective test flow in the project opened. The flows will be added to the API Test Flows folder followed by the deployment folder in the project.

These test flows allow automated testing of the deployed API endpoints as they are fully configured with the relevant test values. Execute the test flows to see if the API calls are running successfully.

This concludes the working of the Test flow generation feature in Astera.

In Astera, Multipart is one of the content types present within the response body of an API flow. It is used for sending and receiving files and textual data. This content type is present in both the API Request and API Response objects.

Multipart Form/Data in Astera

1. To start, create a new API flow.

2. Right-Click on the Request object and select Properties from the context menu.

This will open a new window.

3. Click Next and you will be led to the next screen.

For the Get HTTP Method, Astera supports application/json type.

However, when it is selected to Put, Post, Delete or Patch, you can see the following options in the Content Type dropdown menu.

Multipart Form/Data in the Request Object

For our use case, we have configured our Request object in the following manner. It is a Post request, with the resource BodyAndParams used and the processing type is Synchronous. We aim to upload a file to one of the designated directories from a defined directory with the name we have provided.

4. Clicking Next will allow us to set the directory where we want to receive any text or file. In our case, we are receiving a file.

This is the file that will be received on the user end, i.e., when the user requests it, we will get the file within the request body.

The name of our variable is File and we can select from the following types,

In the Destination Folder column, we have defined the path to a folder where the receiving file will be stored.

The Default Name column allows us to define a name for the file. In this case, the original name of the file will not be used when saving, rather the name that is defined here.

For now, we will keep this section blank.

5. We will click OK and the Request object will be configured.

6. Next, we will deploy the API flow and generate a test flow for it.

7. Next, we will open the test flow that has been generated.

Within the Properties of this object, we can see our entire operation.

8. We will then click Next until we reach the Input Layout window.

9. Here, we can select the file that is to be sent.

10. Making an API Call and previewing the output lets us see that the content we used was sent.

As you can see, our file has also been uploaded to the designated folder.

11. If we send both a file and a text using the Multipart Form/Data option and then preview the output, we can see both in the Data Preview window.

Multipart Form/Data in the Response Object

1. Right-click on the Response object and select Properties from the context menu.

This will open a new window.

Here, you can see the Multipart/Form-Data option in the dropdown menu.

Since in the Request, the file only used to be received so we would select only the path of the folder. Within the Response object, we are sending the file, thus we will need to provide the file path.

2. For our use case, we will select the Multipart/Form-data option, then proceed to the next screen.

Here, we are selecting the directory of the file we need to send, alongside a text.

3. We will then deploy the API flow and generate its test flow.

4. Since this is a Get call, we will be getting our file in the output. Thus, our output content type is Multipart/Form-Data.

5. In the Output Layout screen, we will provide the destination folder of where the file will be saved.

6. We will then click OK and preview our output.

As you can see, the file and the text can be seen in the Data Preview window.

The file path and file name can then be used further within the scope of the flow.

7. Selecting the Create Unique Files for Download option in the Response Options of the API Client object will create a new file every time the call is made.

As you can see below, a new file has been created with a new name.

This concludes the working of the Multipart/Form-Data within the Request and Response objects in Astera.

Video

Using Astera Data Stack, users can design a complete set of API (Application Programming Interface) endpoint flows in a drag-and-drop interface. These APIs can then be deployed to the Astera Server before they can be consumed.

In this document, we will learn how to deploy API flows on the Astera Server. API flows can be deployed individually or as a group set in folder hierarchies.

Deploying a single API Flow

Here, we have a pre-designed API flow,

Let’s see how we can deploy this.

1. Click the Deploy API Flow icon on the API flow toolbar.

Similarly, the Deploy API Flow option from the Project Explorer context menu can also be used. This option is only available for API flows.

The Deployment window will appear like this,

• Method: It’s the HTTPS method selected in the Request object in the API flow.

• Resource: The endpoint defined in the Request object.

• Deployment Name: The name used to refer to this deployment in the Server Browser.

• Example URL: The complete URL that will be used to make the request. It includes the Base URL, Resource, URI, and Query parameters.

• Config File Path: The path of an optional deployment config file to define runtime variables used in the API flows.

2. Define the Deployment Name and the Config File Path (optional). Click OK.

The API Flow is verified in pushdown mode before the creation of the deployment. In case of any verification errors, the deployment will not be created, and the success or failure of deployment status will appear in the Job Progress window. In this case, as you can see, the deployment is completed successfully.

Once the deployment is successfully created, it becomes available in the Server Browser.

This is how you can deploy an API flow. Now, let’s see how we can group and deploy API flows at the folder level.

Group and Deploy APIs

We can group and deploy API flow(s) contained under a folder. All the folder nodes present under the project have the Group and Deploy All API Flows under this Folder option, including the parent .cprj project node. Only the API flows shall be verified and deployed whereas all the other artifacts will not be considered in the deployment process.

1. Right-click on the desired folder and select Group and Deploy All API Flows under this Folder option.

In this example, we have grouped and deployed all API flows under the folder called “Data”. It’s noticeable that the folder, “Data”, has a nested folder, “v1”, under it. In the case of deploying from a folder that contains nested/child folder(s), the name of the nested folder(s) will be appended to the API’s URL as a part of its Resource. For example, ‘’{base URL}/Nested Folder Name/Flow Resource/Parameters’’ such as ‘’https://localhost:9621/v1/{Resource}/{Parameters}.’’

Similarly, we can see a “Dataflow1.Df” artifact under the folder as well. As explained before, this dataflow will not be considered during the deployment process.

After selecting the option, the Deployment window will appear like this,

2. Write the Deployment Name and set the path of the Config File (optional). Click OK.

Success or Failure of the deployment will appear in the Job Progress window. In case of any errors, the verification window can be used to identify and fix errors. As the verification was successful, the API endpoints are visible in the trace.

The successfully created deployment is visible in the Server Browser.

This is how you can group deploy the APIs at the folder level.

The Server Browser in Astera can be used to see all the Deployments/APIs/API services that the user has deployed onto the Astera Server.

API Deployment View

Once we have deployed our API flows, we can see the deployment in the Server Browser,

We can select a different view if we click on the Select Deployment View - Filter option (the filter icon on the left) in the Server Browser toolbar.

Let's select API Deployments from the drop-down menu.

This will open a new view for the user. Here, you can directly see the deployments that have been made by the user(s). If we expand a deployment, we can see all the available endpoints under it.

When we deploy the API flow, a description is automatically added, for each endpoint/API flow. This is with respect to the action performed by the API flow.

Synchronously processed endpoints can be seen with the HTTP method on its own and Asynchronously processed endpoints can be seen with the HTTP method encircled with blue curves.

Active Endpoint View

We can see a consolidated view containing only the active endpoints from each deployment using the following option.

This will show the user a different view,

We can see the endpoints in a tree-like or hierarchical structure. Each endpoint is characterized based on its resource.

Upon hovering over each endpoint, their Request URL can be seen,

Context Options

Deployment Context Options

If we move back to the API Deployment View, we can see some options in the context menu of each of the deployments.

View Deployment: Selecting this option will let the user view the deployment in the deployment manager.

Next, there are a few options present under Swagger Options,

View Swagger UI - Lets the user view the endpoint within a Swagger UI, in Astera Data Stack.

Export as OpenAPI file: Selecting this option will allow the user to generate an Open API specification JSON file which we can export/save to the desired location, be it local or on a network.

Copy Swagger URL: This option lets the user copy the Swagger URL for the deployment. We can use this URL to generate the swagger definition file for the API collection.

Delete Deployment: Selecting this option will remove the selected deployment from the Server Browser.

Generate Testflow for All Endpoints - This option generates test flows for all endpoints present in the deployment.

Endpoint Context Options

Each deployment can either have a single endpoint or multiple ones. Similar to deployment, a context menu is available for each endpoint as well.

Copy URL to Clipboard: This option allows the user to copy the endpoint’s request URL to the clipboard.

Show Runtime Trace: Selecting this option will show the runtime trace for that endpoint.

Deactivate: Selecting this option will deactivate a particular endpoint.

Do Not Require Authentication: Selecting this option will disable the authentication required by this endpoint. To enable the authentication, open the context menu again and select the Authentication Required option.

Generate Test Flow - Select this option to generate a test flow for the selected endpoint.

Security

In terms of security, Astera gives the user the ability to define roles and provide resources to each role.

The security view in the Server Browser can be selected from the Server Browser drop-down menu,

This will open a new view,

Expanding the User and Roles nodes shows us the Astera client’s users and the available roles respectively.

Resources of each role can be allocated by right-clicking on the role and selecting Edit Role Resources from the context menu.

Here, the resources available below are,

• URL

• Cmd

• REST – Publishing and Publishing Async

To assign a role to a user, right-click on the user and select Edit User Roles from the context menu.

Resource Catalog View

We can also view the details of our Resource Catalog in the Server Browser. Simply hover over the Resource Catalog View option from the drop-down menu.

Here, you will be able to see the following options,

View by Artifact Type - Gives the user a catalog view based on artifacts.

View by Namespace - Gives the user a catalog view based on namespace.

Additional Server Browser Options

Apart from the deployment view options, these are the following options also present on the main menu bar of the Server Browser.

Add Deployment: Adds a new deployment

Remove All Deployments: Removes all deployments present on the Server Browser

Expand All: Expands each of the nodes of all the deployments.

Search Bar: Here, you can write a name to search for any specific deployment or an endpoint.

This concludes the Server Browser functionalities for API Publishing in Astera.

Certificate Store

Astera provides users with a certificate store, enabling them to perform essential tasks such as importing, exporting, and generating certificates for various purposes, enhancing security and authentication in the API request using mutual TLS, and providing encrypted communication and data transfers.

1. Right-click on the Default cluster node in the Server Explorer and select Certificate Store from the context menu.

This will open a new window.

Importing a Certificate

1. To import a certificate, select its icon.

This will open a new window.

Client Certificate Type: This option lets you select whether the certificate extension is a Pem file or a Pfx file.

Domain: The domain on which the certificate is to be used when making a connection.

Certificate File: The file path of the certificate to be imported.

Key File: The key file for the certificate which is used for authentication.

Password: This is where we enter the password for our Pfx Certificate for authentication.

2. For our use case, we have imported a certificate from the Astera domain.

Generating a Certificate

1. To start, select the Generate New Certificate option.

This will open a new window.

Domain/Certificate: The domain on which the certificate will be based.

Common Name: The name of the certificate.

Organization Name: The name of the organization to which the certificate belongs.

File Name: The file name of the certificate.

Password: The password for the new certificate.

Signature Algorithm: The algorithm on which the certificate will use the signature.

Validity Period: The expiry date of the certificate, in years.

Key Size: The size of the key for the certificate.

2. For our use case, we have made the following certificate.

Selecting Generate will create the new certificate.

Exporting a Certificate

1. To export the above-generated certificate, select the Export Selected Certificate option.

2. Select the destination folder and the certificate will be exported.

The certificate can then be used elsewhere.

Partner Certificates

Astera allows the user to import certificates as a client.

1. Select the Partner Certificates tab and select Import New Certificate.

This will open a new window.

Certificate Name: This is where the name of the certificate is used.

Certificate File: The file path to the certificate that is to be imported.

2. Selecting Import will Import the certificate.

This concludes the working of the Certificate Store in Astera.

In Astera, users can troubleshoot runtime issues by monitoring live tracing for any APIs deployed on the server.

To configure logging, create a new server profile by right-clicking on the cluster node in the Server Explorer and selecting Server Profiles from the context menu.

This will open a new window.

1. Create a new profile by selecting the Add a new server profile option.

As you can see, we already have a server profile created.

2. Select the Publishing Settings tab and scroll down to the API Runtime logging and tracing section.

Here, the user can select the level of logs to be traced, including information, warnings, errors, or all-inclusive. The logging stages include,

Request Validator Logs: It includes pre-validating the request context before sending it through the runtime processor by validating the server availability, and deployment activity, and inspecting if the request has the supported formats.

Processor Logs: Processor logs include runtime components of the request, including information about a cached request pipeline, the concurrent pipelines in execution, and runtime capacity.

Purge Event Logs After: This counter shows the number of days after which the logs will be purged/removed since a lot of them can accumulate at runtime.

Once the server profile is configured and saved, the next step is to select this profile in the Server Properties.

After logging and tracing have been configured, users can now view the live runtime traces generated for all deployed APIs.

Next, go to the Server Browser and open the Deployed Endpoint View. To view the tracing for any deployed API, right-click and select Show Runtime Trace for any API deployment listed.

You can now see the trace.

This concludes logging and tracing in Astera.

Video

Astera lets users monitor live metrics for all deployed APIs using a Visualization Dashboard.

Select the Plots Explorer view in the Server Browser.

This will open a new view.

Right-click on the option present underneath the Dashboard node and select Open Dashboard from the context menu.

Selecting this will open the dashboard window.

The dashboard shows various performance metrics and graphs which can be used to monitor the deployed APIs. These include,

Total number of requests

Requests per second - Measures the throughput of the API server, gauging the number of requests the server can handle in a time unit of a second.

Average response duration - This is a critical KPI that signifies the average time taken for an API to respond.

Most Recent Logs Record - Lists the 10 most recent requests catered along with detailed information about the server and client.

Requests by Response Status - This shows the percentage of each of the different responses for the deployed APIs.

Requests by Timespan - A bar graph that highlights the traffic received as per the number of requests received with time.

Average Response Duration by Timespan - A line graph showing the average response durations with time.

Using the Data Range filter, all these metrics and graphs can also be filtered by a data view.

From the Server Explorer, right-click on the cluster node and open Cluster Settings. Here, you can set the Purge REST Request Info After value to enable purging the source table.

A value of 0 signifies that the table would never be purged.

This concludes API Monitoring in Astera.