Skip to main content
Docs
Go to the Studio
Roberty Studio
RPAAPIs

HTTP

HTTP

The HTTP module is responsible for making requests to external APIs and for configuring reusable API clients, with a client certificate (mTLS), base URL, default headers and OAuth2 authentication. Its methods can be accessed as in the example below:

js
const apiClient = await API.apiClientCreate["v1_0_0"]({
  baseURL: "https://api.example.com",
});

Methods​

apiClientCreate​

Method responsible for configuring a reusable API client. The returned client is provided in the apiClient parameter of the apiRequest method, which then uses its configuration without having to repeat it in every request.

js
const apiClient = await API.apiClientCreate["v1_0_0"]({
  pfxPath: "C:\\Certificates\\client.pfx",
  passphrase: "certificate-password",
  caPath: "C:\\Certificates\\ca.pem",
  baseURL: "https://api.example.com",
  headers: {
    "Accept": "application/json",
  },
  auth: {
    tokenUrl: "https://auth.example.com/oauth/token",
    clientId: "my-client-id",
    clientSecret: "my-client-secret",
    scope: "read write",
    credentialsIn: "basic",
  },
});

Required parameters​

This method has no required parameters. Provide only the configuration groups the API requires.

Optional parameters​

  • pfxPath:String - expects the path of the client certificate file in the PKCS#12 format (.pfx or .p12), used in requests with mutual TLS (mTLS). The file must exist on the device that runs the robot.
  • passphrase:String - expects the password that protects the certificate file.
  • caPath:String - expects the path of the certificate authority (CA) file that must be trusted when validating the server certificate. It is only used together with pfxPath.
  • baseURL:String - expects the base URL of the API. When provided, the url of the requests made with this client can be a relative path (e.g. /customers).
  • headers:Object - expects an object with headers sent in every request made with this client.
  • auth:Object - configures OAuth2 authentication with the client credentials flow. When provided, the robot gets the access token and sends it in the Authorization header of the requests. Properties:
    • tokenUrl:String (required) - address that issues the access token.
    • clientId:String (required) - client identifier.
    • clientSecret:String (required) - client secret.
    • scope:String - requested scopes, separated by spaces.
    • audience:String - token audience, when the API requires it.
    • credentialsIn:String - expects "basic" (the credentials go in the Authorization header of the token request) or "body" (they go in the body, as client_id and client_secret). When not provided, the credentials go in the header.

Return​

Returns the API client object, which must be stored in a variable (e.g. apiClient) and provided in the apiClient parameter of the apiRequest method. When auth is provided, the object also keeps the token obtained (accessToken, tokenType and expiresAt), reused by the following requests.

The method validates the configuration right away: if the certificate cannot be read, the password is wrong or the token cannot be obtained, the robot stops the execution with an error already in this method, and not only on the first request.

apiRequest​

Method responsible for making an HTTP request to an API.

js
const apiResponse = await API.apiRequest["v2_0_0"]({
  url: "/customers",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: {
    name: "John",
  },
  apiClient: apiClient,
});

Required parameters​

  • url:String - expects the request address. When the apiClient has a baseURL, it can be a relative path.
  • method:String - expects "GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH", "HEAD", "CONNECT" or "TRACE".

Optional parameters​

  • headers:Object - expects an object with the request headers. When used with apiClient, the headers provided here take precedence over the client's headers and over the Authorization generated from the token.
  • body:Any - expects the request body.
  • apiClient:Object - expects the API client returned by the apiClientCreate method. When provided, the request uses the client's certificate, base URL, default headers and token. If the API responds with status 401, the robot gets a new token and repeats the request once.

Return​

js
actions.apiResponse.status // HTTP status code of the response (Number)
actions.apiResponse.statusText // HTTP status text of the response (String)
actions.apiResponse.response // response body (Any)

When the API responds with an error status, the method rejects the promise with an object that has the same status, statusText and response properties. If there is no response (network failure), status is 0 and statusText is "Network Error".

Version v1_0_0 of this method accepts only url, method, headers and body, and returns only response.