What is an API Endpoint?

The structure of the URL is as follows:

https://<<Server Name>>/phixflow/api/1/action/<<Application Name>>/<<Actionflow Name>>/trigger

Input Parameters

Image Removed

On the Input Connection Point, additional Input Parameters can be created to facilitate query string parameters being passed into the API via the URL.

If a parameter is missing then it will be marked as unavailable, unless a Default Value has been configured. 

1. Configure the API to perform the required tasks, for example return all company data , or pass in a date and return all companies onboarded after this date
   1. See Worked Example below for an example setup

Input Parameters

Image Added

On the Input Connection Point, additional Input Parameters can be created to facilitate query string parameters being passed into the API via the URL.

1. Click on the

   Insert excerpt
   _input _input nopanel true

   node
2. The

   Insert excerpt
   _property_settings _property_settings nopanel true

   will open on the right and in the Input Parameters section, click the 

   Insert excerpt
   _add_icon _add_icon nopanel true

   icon to create a new attribute
3. Enter a Name and Default Value (optional)

The Name set on the

If a parameter is missing then it will be marked as unavailable, unless a Default Value has been configured. 

URL & URL Alias

URL and URL Alias can be found on the API Endpoint

• Copy the URL and save it locally, to be used later when calling the API
  

  Expand
  title Url Structure
  The default structure of the URL (i.e. with no URL Alias set) is as follows: https://<<Server Name>>/phixflow/api/1/action/<<Application Name>>/<<Actionflow Name>>/trigger Parameter Description <<Server Name>> URL of the server e.g. app.phixflow.com phixflow the name of the instance, typically this is phixflow <<Application Name>> The name of the application where the Actionflow resides. <<API Name>> The name of the API. Note: If the API Name contains a space, this is replaced with %20. For example "My API" becomes, "My%20API".

  
  

• Use URL Alias to modify the URL for the API
  • When set, instead of the URL being constructed using the API Endpoint name and application name, it will use the alias instead

URL Alias Example

If the API URL is, https://server.phixflow.com/phixflow/api/1/action/My%20App/My%20API%20Endpoint/trigger and a URL Alias of CompanyData is set, then the API URL will change to, https://server.phixflow.com/phixflow/api/2/CompanyData

API Mode

API Mode can be found on the API Endpoint

Choose an API Mode:

• Wait for result (Synchronous) (Default): The API waits for the results or the timeout to occur
  • Note: If the timeout occurs the command is aborted
• Poll for result (Asynchronous): The API is called and a response is returned immediately including the process ID
  • Subsequent API calls can be made using the process ID to fetch the status of the action
  • The asynchronous mode can be thought of as “fire and forget”

Authorisation

Allow Anonymous Connections can be found on the API Endpoint

If Allow Anonymous Connections is enabled:

Note: Adding authorisation is covered on API Authentication and Secret Keys.

Timeout

Timeout can be found on the API Endpoint

Set a Timeout (optional):

• Specify a maximum time in milliseconds that the API will wait for before the command is aborted

• When a Timeout value is set, it overrides the default timeout, which is 60 seconds where API Mode is Synchronous and 500 milliseconds where API Mode is Asynchronous

  • However, if a timeout parameter has been provided in the URL calling this API, that will override both this Timeout value and the default value

API Status Check (Poll for Result)

• If calling a PhixFlow Asynchronous API only, a result will be immediately returned which includes a Process ID for that run
• The Process ID is returned on the path:
  • $.processId
  • This can be accessed in an Output attribute using, _result.value
• The Process ID can be used to call the following URL which will return the current state of the run:
  • https://<<Server Name>>/phixflow/api/1/action/<<Application Name>>/<<Actionflow Name>>/poll/<<processID>>

Calling a PhixFlow API

HTTP Method

This is set on the 

• To call a PhixFlow API use the HTTP Method GET or POST:
  • GET simply calls the API with data passed in the body of the request
  • POST calls the URL and sends data in the body of the request. The body data is passed into the body attribute of the API as an Input Connection point

Returned Data JSON Path

If your API has been configured to return data the path will be in the format:

$.data.<<Output Name>> 

Where <<Output Name>> is the Output connection point.

Server Console Responses

The item calling the API endpoint will receive the Response from the API endpoint stating whether it has run successfully (Success) or not (Fail). Responses can be customised to return specific messages.

The response recorded in the

If you are making the call using PhixFlow the Responses can be access as follows:

1. Click the Actionflow entry
   1. 
2. In the Messages section which is opened below, double-click the lines that begin Response
   1. 
3. Click the Message Details tab to see the response

API Endpoint Results

To see the results of the API Endpoint processing in the 

1. Click the Actionflow entry for the API Endpoint
2. In the Messages section which is opened below, double-click any of the Messages to see more details
3. If you are using a debug() statement these will appear here

Failures

An API Endpoint will fail if the logic in the Actionflow fails or if the error() function is used to force a failure.

If records are passed to the API Endpoint individually a failure will only impact the specific record being processed.

Error Codes

200

• Occurs if the output of an API Endpoint is not connected

• Occurs if the output is connected and a record is returned 

400

• Occurs if the output is connected but no record is returned 

Worked Example

Here's a worked example using the Company Data (available from the Learning Centre).

In this example, we are using:  

• A Company Call API screen containing a fixed drop down list of industries, a string fields for the API Status and a multi-line string field for the Results - this screen was created using the Tile with Buttons template