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.

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.

1. 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.

1. 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.

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

1. 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.

1. 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.

1. 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.

1. 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.

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

1. 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.

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.

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

This will open the configuration window for the object.

1. 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.

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

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.

1. 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.

1. 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.

1. 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.

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

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

1. 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.

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.

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.

1. 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.

1. 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.

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

This will open a new screen,

1. 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.

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

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

1. 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.

1. Click OK.

The parameters have been added.

1. 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.

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.

1. 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.

1. 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.

1. 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.

1. Selecting Import will Import the certificate.

This concludes the working of the Certificate Store in Astera.

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.

1. 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,

1. 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.

1. 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.

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

We have named our first request as ‘Async’.

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

We can see the respective Postman request below,

1. 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.

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

1. 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.

1. 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.

1. 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,

1. 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.

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.

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

This will open a new window.

1. 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.

1. 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.

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

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

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

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

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

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

1. 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.

1. 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.

1. 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.

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

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

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

1. 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.

1. 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

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.

1. 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.

1. 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

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.

1. 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.

1. 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.

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.

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

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

1. 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.

1. Select both checkboxes and provide a file path.

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

1. 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.

1. 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.

1. 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.

1. 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”

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

1. Browse your desired file to the VALUE,

1. 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.

1. 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.

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

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

1. 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.

1. 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.

1. 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.