Documentation › Call an API

Call an API from a step

A Task step can call an external service (REST, SOAP or GraphQL): the person who does the task clicks a button, the service answers, and the values of the response go into variables of the process.

How it works

1. The designer opens the Task step in the editor and defines the call in the API call tab: where to call, with what, how to sign in, what to expect back and which values to keep.
2. The definition is stored with the process. Nothing is called when the process is published.
3. In a process instance, the person who does the task sees an API call panel and clicks Call the API.
4. The response is shown, and the values kept are written into the outcomes (Outcomes) of the task, so into the variables of the process.

Define the call (API call tab)

In the form of the Task step, open the API call tab and click Add an API call. The Remove the API call button takes the call off the step, and the Documentation link opens this page. In front of each field, the (i) button explains what to type, with an example, and links to the matching section of this page.

The request

• Kind of call: REST (a simple HTTP request), SOAP (an XML message sent to a web service) or GraphQL (a query sent to a single address).
• Method (REST): GET reads, POST creates, PUT replaces, PATCH changes, DELETE removes, HEAD and OPTIONS. SOAP and GraphQL always use POST.
• Address (URL): the full address, starting with http:// or https://.
• Time to wait for an answer (seconds): from 1 to 120, 30 by default.

Path parameters: /{id}/{name}

Write the parts of the address that change between curly braces, for example https://www.site.com/{id}/{name}. In Path parameters, the Add the parameters of the address button creates one row per part; give each its value, typed here or taken from a variable (link button). The value is encoded for you: spaces and slashes do not break the address.

• Each part between curly braces must have its row, and each row must be used by the address: otherwise the publication is refused with a message that says so.
• Do not mix them up with a variable of the process, which is written ${VariableName} (see Use the variables).

Query parameters and headers

Query parameters (added to the address: ?page=2&size=10) and Headers are “name / value” rows. Untick Send to keep a row without sending it. Content-Type is set from the type of body: write it only to use another one.

The body

• REST (Body): none, JSON, text, XML, form (URL encoded) or form (multipart). In a text, ${Variable} is replaced by the value, escaped for the type: {"customer": "${Customer}", "quantity": ${Quantity}} (a variable that holds a number is written without quotes).
• SOAP (SOAP message): the version (1.1 or 1.2, the one of the WSDL of the service), the action (SOAPAction, for example http://tempuri.org/GetPrice) and the message: the whole envelope, or only the content of its Body (the envelope is then added).
• GraphQL (GraphQL document): the query, for example query GetUser($id: ID!) { user(id: $id) { name } }, its variables as JSON ({"id": "${UserId}"}) and the operation name when the document holds several.

Authorization

Authorization: secrets are hidden while typed and can come from a variable.

• Basic: user name and password.
• Bearer token: a token, sent after the word Bearer (or the prefix you give).
• API key: the name of the key (for example X-Api-Key), its value, and where to send it (in a header or in the query parameters).
• OAuth 2.0: the call first gets a token from the token service (Address of the token service, often ending with /token) with the client id and secret (Client id, Client secret) and, as you choose, the Scope asked or a user name and a password. Tick the box to send them in the body if the service does not want a header.
• Digest: the service challenges the call, the hashed answer is sent automatically.

User authentication

When a service asks the person to log in, tick This call logs the user in (User authentication section). Draw this call, or these calls (one per step), according to the authorization of the service: token, session, etc.

• In the process instance, the person who does the task sees a user name, a password and the Log in button instead of Call the API.
• Write ${Login.Username} and ${Login.Password} in the address, headers, body or authorization (for example the user and password of a Basic authorization).
• Extract the token (JsonPath) or the session (Set-Cookie header) into variables: the next calls use them (Bearer token, Cookie header).
• The user name and the password are never stored, and the response of the login is not shown: only the values kept in the variables are.

The expected response

• Response type: what the body of the response is (JSON, XML or text). Choose it to be warned when the service answers something else. It also decides the ways to read a value: a JSON path for JSON, an XPath for XML; Any (not checked) checks nothing.
• Status codes: the codes that mean success, for example 200-299,404. Any other response makes the call fail.
• Example of a response: a reminder for you, not checked.

A call also fails when the service answers with a SOAP Fault or GraphQL errors, even with a 200 status.

Values to extract from the response

Values to extract from the response: each row reads a value in the response and puts it in a variable of the process. An outcome (Outcomes) is added to the step for each variable.

• Read from: JSON path, XPath, Response header, Status code or Whole body. The choices follow the type of the response.
• Path or name:
  • JSON path: $.data.id, $.items[0].name (first element), $.items[-1] (last), $.items[*].id (every element), $..id (anywhere), $['a b'] (a name with a space).
  • XPath: //GetPriceResult, //Item[1]/@id, count(//Item). Namespaces are ignored.
  • Header: its name, for example ETag.
• Variable: the variable that receives the value. A number, a date (2030-03-15), a yes/no (true, yes, 1), an email address or the name of an option (list variable) must fit the type of the variable.
• Required: when the value is missing or does not fit, the call fails (otherwise the value is skipped).

Use the variables of the process

• For the value of a row or a secret, click the link-shaped button: the value is then taken from a variable when the call is made (a Process or Global variable).
• In an address or a text (body, SOAP message, GraphQL query), write ${VariableName}, or use Insert a variable in the text. The value is escaped for where it goes (JSON, XML, address).
• A variable without a value when the call is made stops it: nothing is sent and the message names the missing variables.
• A call can use what an earlier call kept: for example a token got by a first task and used as the Bearer token of the next one.

Make the call in a process instance

On the page of a task of a Task step that has a call, the API call panel sums the call up (kind, method, address, authentication, expected statuses) and lists the Extracted values. Click Call the API:

• The Response card shows Succeeded or Failed, the status, the duration, the body (JSON is formatted) and the headers.
• Values from the response tells, for each value, Applied or Not applied (with the reason). The outcomes of the task and the variables are updated.
• When the call fails (service unreachable, unexpected status, SOAP fault, GraphQL errors, required value not found, value that does not fit the type of the variable), no variable is changed.
• You can make the call again: the values are replaced.

Security and limits

• The secrets typed in the definition are stored with the process and are never sent back to the people who do the task.
• The call is made by the ProcNest server: addresses of a private network (localhost, 10.x, 192.168.x, cloud metadata services…) are refused, unless the administrator allows them.
• The body of the response is cut beyond about 1 MB; a value can then no longer be read reliably.

Tips

• Try your service with a tool such as Postman before defining it here: the fields are the same.
• Pick a response format (JSON or XML) to be warned when the service answers something else.
• A value for a list variable (simple list, multi-choice list) must be the name of one of its options.