> For the complete documentation index, see [llms.txt](https://documentation.astera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.astera.com/astera-data-stack-v9/api-flows/api-consumption/consume/rest-connection.md). # REST Connection To make an API call in Astera, a *REST Connection* object needs to be configured first. {% embed url="" %} ## **Configuring The REST Connection Object** 1. Drag-and-drop the *REST Connection* object from the Toolbox onto a dataflow. {% hint style="info" %} **Note:** This can also be done in a shared action. This will be covered in more detail at a later stage in the article. {% endhint %} ![](/files/dESupobKiXFwjqs4fIw7) 2. Right-click on the *REST Connection* object and select *Properties* from the context menu. ![](/files/6ScwQFiVLSHQpZikPaAb) A configuration window will appear on your screen. ![](/files/aExYDWkXiU4Spo9k1CLM) * *Base URL:* Here, you can specify the base URL of the API which will prepend as a common path to all API endpoints sharing this connection. A Base URL usually consists of the scheme hostname and port of the API web address. {% hint style="info" %} **Note:** When a user imports an API definition, a shared connection file containing the *Base URL* and authentication type is automatically created within the project. To learn more about importing APIs in Astera, click [here](https://documentation.astera.com/v/astera-data-stack-v9/api-flows/api-consumption/consume/rest-api-browser). {% endhint %} * *Timeout (msec):* Specify the duration, in milliseconds, to wait for the API server to respond before giving a timeout error. ![](/files/1QbOx1vVanVzu8qoYXCN) * *Authentication – Security Type:* Specify the authentication type for the API. Astera supports the following authentication types: ![](/files/7vte2zudUfWOODtmfCX5) ## **Types Of Authentications:** The following authentication types are supported in Astera: 1. *No Authentication* 2. *OAuth 2* 3. *API Key* 4. *Basic Authentication* 5. *Bearer Token* ***No Authentication*** With this security type, the user can send API requests without including any authentication parameters. ![](/files/6hsHCsXmVU1ePDdABIjl) ***OAuth 2*** This type is used when an application requires permission to access data on your behalf. Instead of giving away your password to the application, *OAuth 2* enables delegated authorization through a third-party Auth Server. In response to a valid authorization, the Auth Server issues an Access Token with a restricted scope and validity. When the Access Token expires, its Refresh Token is used to obtain another valid Access Token. Configure an *OAuth 2* request to generate Access and Refresh tokens. The tokens will be implicitly added to the request and auto-refreshed if expired. In the *OAuth 2* authentication, you can select any of the four *Grant Types*: 1. *Implicit* 2. *Authorization Code* 3. *Password* 4. *Client Credentials* ***Implicit*** In this *Grant Type*, you only need to provide an *Authentication URL* and *Client ID* to request a token without an intermediate code exchange. It was built for Javascript client applications that receive the token directly exposed in the HTTP URL. Hence, this type is considered less secure for web applications and is replaced with an Authorization Code. ![](/files/gCvotAmYaa0N8Zgx3P66) * *Authentication URL:* This is the login page, where the API user authorizes itself to the Authentication Server. * *Client ID:* This is the public identifier for accessing the registered API Server application. ***Authorization Code*** This flow type is popular for server-side applications. In this *Grant Type*, you need to provide an *Authentication URL*, *Access Token URL, Client ID*, and, optionally, a *Client* *Secret* to authorize. On authorizing, the flow first returns a one-time Authorization Code to the client. This code is then exchanged for an Access Token. ![](/files/9J23yTInthbiIL2ceZqD) * *Authentication URL:* This is the login page, where the API user authorizes itself to the Auth Server. * *Access Token URL:* This URL is provided to generate an Access Token for authentication after the user has been authorized successfully. * *Client ID:* The public identifier for accessing the registered API Server application. * *Client Secret:* It is provided alongside the *Client ID*, as a secret credential to access the registered application from the Auth Server. ***Password*** In this *Grant Type*, you need an *Access Token URL, Username, Password*, *Client ID,* and *Client Secret* to authorize. It is considered for internal services and not recommended for third-party applications as it authenticates the given credentials in a single step. Since user credentials are exposed to the client application, this flow type outlaws the OAuth principles and is now deprecated.
* *Access Token URL:* The URL through which the Access token is going to be generated for authentication. * *Username:* The application login name of the user for authentication. * *Password:* The application user password is provided for authentication. * *Client ID:* The public identifier for accessing the registered API Server Application. * *Client Secret:* It is provided alongside the Client ID, as a secret credential to access the registered application from the Auth Server. ***Client Credentials*** In this *Grant Type*, you need the *Access Token URL, Client ID,* and *Client Secret* to authorize. This is used with the client application. It self-authenticates access to its resources without a user context. ![](/files/RCgUSYKfXUfg2p0UpK4e) * *Access Token URL:* This URL is provided to generate an access token for authentication. * *Client ID:* The public identifier for accessing the registered API Server application. * *Client Secret:* It is provided alongside the Client ID, as a secret credential to access the registered application from the Auth Server. **API Key** An *API Key* is a key-value pair that a client provides when it makes an API request. They can be sent in the *Query* string or as a request *Header*. ![](/files/i3oo9OVGlsMHOUyBgPcE) It requires two parameters for authentication: 1. *Key* 2. *Value* ***Basic Authentication*** *Basic Authentication* is structured according to the HTTP protocol to provide a *Username* and *Password* when making a REST request. In basic HTTP authentication, a request contains a header field in the form of Authentication: Basic, where credentials are the Base64 encoding of ID and password joined by a single colon. ![](/files/DEQ8id0GoOinIWuG5Y0w) ***Bearer Token*** *Bearer Token* or token authentication is an HTTP-based authentication. The access token is a text string included in the request header. It is generated by the server in response to a login request. ![](/files/fh8EjGotoVA1jdDKLywi) To generate a *Bearer Token*, you need: * *User Name* * *Password* * *Token URL* 1. Once the *Security Type* has been selected, click *Next* and you will be led to the next screen. **Shared Parameters** Once done, the *Parameters* screen is opened. This is where you can define parameters based on your requirements, be it a *Query* or a *Header* parameter. ![](/files/1L1m4spnyyRg5L9Ai7HF) ![](/files/P4SdgtOK6l3uYYSV5hQW) *Name:* The name of a *Query* or *Header* parameter can be defined here. ![](/files/QKoRaCTSUSIhOr3qol3n) *Parameter Location:* This option defines whether the parameter has a *Query* location or a *Header* location. ![](/files/VY7XY7WtazzVxXO0sJsd) *Data Type:* This option defines the data type of the parameter from a list of options. ![](/files/zn6Ef8EuPrHDfDEac1Xh) *Default Value*: Values added here will be used throughout the pipeline unless defined otherwise. The parameters defined here will be inherited in all REST Clients that use this shared connection. 2. Once done, click *Next* and you will be led to the *Config Parameters* screen. ![](/files/TKrPVKGRsoHcZF9qKLRg) Here, config parameter values can be changed according to your application. Parameters not changed will use their default values. 3. Click *Next,* and you will be led to the *General Options* screen. ![](/files/UhCwjMOwKzYYMct7ecTv) Here, you can add any *Comments* that you wish to add. The rest of the options for this object have been disabled. 4. Click *OK* to close the window. You have successfully configured the *REST Connection* object. ![](/files/E17o0uDuT3aBA8aGl4Rq) ## **Using the REST Connection Object** **In a Dataflow** 1. Click on *File* in the main toolbar, hover over *New*, and select *Dataflow* from the drop-down menu. ![](/files/dV0LCTYH3bk4avndM5MX) 2. Once the dataflow is open, drag-and-drop the *REST Connection* and *REST Client* objects from the Toolbox onto the dataflow.
{% hint style="info" %} **Note:** The *REST Connection* here can only be accessed within the scope of this dataflow. {% endhint %} 3. Configure the *REST Connection* object for the Base URL and Authentication. Right-click on the *REST Client* object and select *Properties* from the context menu.
A new *REST Client* Properties window will open.
The *Shared Connection* dropdown list shows us the *RESTConnection* objects present in the same dataflow.
You can now use this *REST Client* object to make API calls within Astera. **In a Project** 1. Navigate to the main toolbar, click *Project*, hover over *New*, and select a project type. Please click [here ](/astera-data-stack-v9/project-management/project-management/astera-project-and-project-explorer.md)for more information on creating projects. {% hint style="info" %} **Note:** You can also open a previously existing project. {% endhint %}
2. Locate the Project Explorer on the right, right-click on the project or one of its folders, and select *Add New Item* from the context menu.
This will open a new window where a new *SharedAction* can be added to the project.
3. Within the *SharedAction* file, drag and drop the *REST Connection* object from the Toolbox. {% hint style="info" %} **Note:** The *SharedAction* file should only contain a single *REST Connection* object. {% endhint %}
4. Configure the *REST Connection* object with *Base URL, Authentication, and Shared Parameters* and save the *SharedAction* file This *REST Connection* can be used in any flow document contained in the same project. 5. Next, open a new dataflow within the project.
6. Drag-and-drop the *REST Client* object onto the dataflow, right-click on it, and select *Properties* from the context menu.
A new window will open. Here, you can see the name of the *Shared Connection* within the drop-down menu of the *Properties* option. {% hint style="info" %} **Note:** Within the project, the shared *REST Connection* can be accessed within any flow. {% endhint %} This concludes our discussion on the configuration and use of the *REST Connection* object in Astera. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.astera.com/astera-data-stack-v9/api-flows/api-consumption/consume/rest-connection.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.