REST Client Resource (Magic xpi 4.13)
The REST Client resource is used to define the RESTful API server URL and the operations exposed by the server. A user is expected to know what is the Server URL, Paths and operations exposed by the RESTful API provider. The user can define one security type per resource. The resource can have one or more Paths to define the API and for each Path user can define the Query Parameters, Header Parameters, and Form Parameters.
REST Client resources contain the following parameters (the parameters in bold are mandatory):
|
|
|
|
Server URL
|
Server URL is also known as base path which will be used to define the API endpoint. The server URL and the Path will create one API endpoint URL that can be invoked for HTTP operations like Get, Post etc.
Enter the REST server URL or click  to open the Environment Variable List. Here, the user can select an environment Variable to use as a server URL.
|
|
The Server URL should not start with or end with the dot (.) and slash (/) characters. Apart from this, the characters which are not allowed to be used as a part of Server URL are [space] < > { } | \ ^~ #
|
|
|
Security
|
Security type is used based on what type of security server has implemented.
This is a combo-box. Select the required security type from the drop-down list.
-
None (default)
-
HTTP-Basic
-
HTTP-Digest
-
OAuth2
|
|
User
|
The username for authenticating the REST Client resource when the user selects HTTP-Basic or HTTP-Digest security type.
|
|
Password
|
The password for authenticating the REST Client resource when the user selects HTTP-Basic or HTTP-Digest security type.
|
|
OAuth Refresh Token Status
|
Indicates whether a refresh token was successfully obtained when the OAuth authorization process was performed. The possible values are:
-
Missing (default)
-
Available
|
|
Authorization URL
|
The Authorization endpoint is used to interact with the resource owner and get the authorization to access the protected resource.
Enter the Authorization URL or click to open the Environment Variable List. Here, the user can select an environment Variable to use as an Authorization URL.
|
|
Access Token URL
|
The Access Token endpoint is used by the application in order to get an Access Token or a Refresh Token.
Enter the Access Token URL or click to open the Environment Variable List. Here, the user can select an environment Variable to use as an Access Token URL.
|
|
Callback URL
|
When requesting Authorization code through Authorization URL, the Callback URL will be passed as value for parameter called redirect_uri. A successful response from Authorization endpoint results in a redirect to this URL.
Enter the Callback URL or click to open the Environment Variable List. Here, the user can select an environment Variable to use as a Callback URL.
|
|
Client Id
|
The Id of the application that asks for authorization. Client Id and Client secret are generated at the time of client registration process at the Authorization server.
Enter the Client Id or click to open the Environment Variable List. Here, the user can select an environment Variable to use as a Client Id.
|
|
Client Secret
|
The secret string provided for the Client Id during the Authorization process.
Enter the Client Secret or click to open the Environment Variable List. Here, the user can select an environment Variable to use as a Client Secret.
|
|
Scope
|
Scope is option in case some Authorization server has defined scope and expecting Scope to be sent while retrieving the OAuth Access/Refresh Token.
Enter the Scope or click to open the Environment Variable List. Here, the user can select an environment Variable to use as a Scope.
|
|
State
|
Some REST Endpoints may require the user to provide the "State" parameter during the OAuth process. The parameter is usually required for a more secure authentication system. The OAuth authentication may fail if the required state value is missing or incorrect. This is required to prevent Cross Site Request Forgery (CSRF).
(Since version: 4.13)
|
REST Client resources also give you the following buttons:
|
|
|
|
Access Token
|
Click this button to retrieve the Access/Refresh token when OAuth2 is selected as a security type.
On clicking the button the OAuth authorization process will be initiated. This process will take the user to the Authorization grant page in the browser window where the user can log in using User and Password and provide the access grant to allow the REST component to access the resource on the OAuth Authorization window. The process uses grant type as Authorization code where the following parameters will be used.
-
Authorization URL
-
Access Token URL
-
Callback URL
-
Client Id
-
Client Secret
-
Scope (Optional)
The user should provide these values and click the Generate Token button to get the access token from the provider. Once this operation is complete the OAuth Refresh Token Status parameter (above) will be set to Available.
|
|
Paths
|
Path is generally the route through which the user can access the REST API. The value of the Path parameter will be appended to the Server URL in order to form REST API endpoint. The Path is URL path and when combined with HTTP verb like Get or Post etc., it becomes one unit for one API call.
Click on the Paths button to define the Paths to be used by the REST Client. On the Paths window the user can add or remove the Query Parameters, Header Parameters, Form Parameters for each path. For more information, click here.
|
(Since version: 4.9)
