Methods

Methods will help you get, modify and transform data, no matter where that data came from. Like from the incoming request, such as query/header parameters, requestbody or data requested with a fulfillment from any datasource.

It´s important to understand that any data (no matter where from) is internally processed as JSON. Therefore you are able to retrieve single data points from a response with JSONPATH. For example, even though you have received data from an SQL Query you are still able to get the column testcolumn by using the JSONPATH $.testcolumn

Overview

Method	Parameter 1	Parameter 2	Description
VALUE	The data defined with a fulfillment name	JSONPATH syntax	A method to run a JSONPATH on a JSON.
PARAM	Query/Header Parametername	-	Get the value for a certain request input parameter.
BODY	-	-	Get the request body (if available).
TEXT	Text	-	Set a hardcoded text.
INTEGER	Number	-	Set a hardcoded integer.
LONG	Number	-	Set a hardcoded integer.
DOUBLE	Number including decimal	-	Set a hardcoded double.
BOOLEAN	true or false	-	Set a hardcoded boolean.
NULL	-	-	The value null.
JSON_FROM_STRING	JSON	-	Used to decode a json from string attribute.
LIST	Array size	-	Build an empty list with the size of Parameter 1.
SIZE	A Json Array	-	Get the size of a Json Array.
MULTIPART_FILE_CONTENT	The multipart key (from the request)	-	Read the filestream from the incoming request by using the multipart key.
MULTIPART_FILE_NAME	The multipart key (from the request)	-	Get the filename from the incoming request by using the multipart key.
MULTIPART_FILE_CONTENTTYPE	The multipart key (from the request)	-	Get the filename from the incoming request by using the multipart key.
GET_JSON	A fulfillment name	-	Get the result from a fulfillment a json.
LIST_TO_STRING	4 Parameters (see details below)	-	Build a string from a list of string, with the options for prefixes and seperator.
VALUE_BY_INDEX	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.
NOW	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.
DATEFORMAT	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.
STATUSCODE	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.
ENV	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.
LENGTH	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.
SUBSTRING	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.
LOOPINDEX	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.
LIST_BY_VALUES	3 Parameters (see details below)	-	Retrieve a value of an indexed fulfillment.

VALUE

With the VALUE function you are able to access data (like from other fulfillment results) and get specific values from the JSON by using the JSONPATH syntax.

VALUE(param1, param2)

Param 1 - Input JSON

The input JSON could originate from various datasets:

Parameter 1	Example	Description
Fulfillment Name	VALUE(ff_name_1, JSONPATH)	Access the result (data) of a fulfillment.
@	VALUE(@, JSONPATH)	When building Json Array you may use the @ to access the current entry in a loop.
@@	VALUE(@@, JSONPATH)	If you want to get the data from the loop in front of the current one.
JSON_FROM_STRING	VALUE(JSON_FROM_STRING(VALUE(ff1, $.escapedjson)), JSONPATH)	Get a JSON from another escaped JSON field.

Param 2 - JSONPATH syntax

Your jsonpath syntax. See the documentation for more information.

HINT Use the JSONPATH Online Syntax Editor for testing your syntax: https://jsonpath.com

PARAM

Get the value for a certain request input parameter. You may request both query or header parameters this way.

PARAM(Content-Language)
PARAM(userId)

BODY

Use the BODY() or BODY(jsonpath) method to retrieve the whole incoming requestbdoy or parts of it with jsonpath. When used without a parameter, it returns the full request body. When used with a JSONPath parameter, it extracts a specific field from the request body.

Examples: - BODY(): Returns the full request body. - BODY($.element.id): Returns the id field from the element object in the request body.

TEXT

Set a hardcoded text. Whenever you just need to set a hardcoded text/string, you may do this with the method TEXT(string)

TEXT(This is an example text)
TEXT(I can put every hardcoded string in here!)
TEXT() ## emtpy string, useful for condition comparison.

INTEGER

Set a hardcoded integer.

INTEGER(0)
INTEGER(150)
INTEGER(-210)

LONG

Set a hardcoded long.

LONG(0)
LONG(1729168465000)

DOUBLE

Set a hardcoded double.

DOUBLE(1.3)
DOUBLE(15.82)

BOOLEAN

Set a hardcoded boolean.

BOOLEAN(true)
BOOLEAN(false)

NULL

When building a condition you sometimes want to check for null values. Use the NULL() method for that.

NULL()

JSON_FROM_STRING

Used to decode a JSON from string attribute. This is usable for results you get from a 3rd party request or database columns where an escaped JSON input is within a attribute. After escaping a JSON you may use it within a VALUE method to filter.

Used in combination with a VALUE method.

JSON_FROM_STRING(VALUE(fulfillment_name, $.content.escapedjson)

LIST

Returns a list with an index (starting with 1). You may use List to build Loop fulfillments with a hardcoded number of iterations, or for building a request schema with a fixed size.

LIST(1)
LIST(3)

Example on usage:

  - name: loop_ff
    type: loop
    loop: LIST(20)
    fulfillments:

      - name: ff_example
        type: READ
        datasource: api
        instructions:
          - request:
              ## Use VALUE(loop_ff, $) to get the current index of the loop LIST() starting with 1.
              url: "https://www.example.com?page=${VALUE(loop_ff, $)}
              httpType: GET

SIZE

Get the size of a JSON Array. Used in combination with the VALUE method.

SIZE(VALUE(fulfillment_name, $))
SIZE(VALUE(fulfillment_name, $.news))

MULTIPART_FILE_NAME

Returns the name of the uploaded file for the given multipart_key.

MULTIPART_FILE_NAME(multipart_key)
MULTIPART_FILE_NAME(file)

MULTIPART_FILE_CONTENT

Returns the content of the uploaded file for the given multipart_key.

MULTIPART_FILE_CONTENT(multipart_key)
MULTIPART_FILE_CONTENT(file)

MULTIPART_FILE_CONTENTTYPE

Returns the content type of the uploaded file for the given multipart_key.

MULTIPART_FILE_CONTENTTYPE(multipart_key)
MULTIPART_FILE_CONTENTTYPE(file)

GET_JSON

Get the result from a fulfillment a json.

GET_JSON(fulfillment_name)
GET_JSON(ff1)

LIST_TO_STRING

Build a string from a list of string, with the options for prefixes and seperator.

LIST_TO_STRING(fulfillment_name, JsonPath, Prefix (Use %s as placeholder for your list value), Seperator)
LIST_TO_STRING(ffname, $.list, "entry:%s", "||")
LIST_TO_STRING(ffname, $.list, "Placeholder %s here", "")

VALUE_BY_INDEX

If you have a fulfillment which is running multiple times in a loop, it makes sense to index this fulfillment. After doing so you are able to access indexed fulfillments by using the VALUE_BY_INDEX method. Add the fulfillment name and the index as second parameter to get the result. The second parameter must be from another method such as VALUE or NUMBER, TEXT.

VALUE_BY_INDEX(Fulfillment Name, Index Value, JsonPath)
VALUE_BY_INDEX(ff1, INTEGER(1), $.list)
VALUE_BY_INDEX(ff1, VALUE(ff2, $.id), $.list)

NOW

The NOW() method returns the current time in Unix timestamp format (seconds since January 1, 1970). You can use this to get the current time and then convert it to a desired format.

DATEFORMAT

The DATEFORMAT method helps you convert between different date formats. It supports three different usages:

DATEFORMAT(date, dateTo): Converts the given date to the specified dateTo format.
DATEFORMAT(date, dateTo, timezone): Converts the given date to the specified dateTo format in the provided timezone.
DATEFORMAT(date, dateTo, timezone, dateFrom): Converts the given date from dateFrom format to dateTo format in the provided timezone.

For timezones, APICHAP follows the standard names like UTC or Europe/Vienna. For a list of supported timezones, refer to this resource.

Examples:

DATEFORMAT(VALUE(@, $.created_at), "MM-dd-yyyy"): Converts the created_at value to the MM-dd-yyyy format.
DATEFORMAT(NOW(), "dd.MM.yyyy", "UTC"): Returns the current date in dd.MM.yyyy format in the UTC timezone.
DATEFORMAT(TEXT(12.12.2024), "dd.MM.yyyy", "UTC", "MM-dd-yyyy"): Converts the date 12.12.2024 from MM-dd-yyyy to dd.MM.yyyy format in the UTC timezone.

APICHAP processes all dates and times as Unix timestamps by default. This means whenever you read a date or time from a database, it will be a long number representing seconds since 1970 (Unix time). You can use DATEFORMAT to convert these values into a more readable format.

STATUSCODE

The STATUSCODE() method allows you to retrieve the status code returned by a specific fulfillment. This is useful when you want to handle failures but don't want the operation to abort.

Example usage of STATUSCODE():

- name: check_status
  type: generic
  instructions:
    - if: STATUSCODE(some_request) != 200
      # Handle failure case

In this example, STATUSCODE(some_request) retrieves the status code returned by the some_request fulfillment.

ENV

Use the ENV variable when your configuration contains values that are either changing between differnt environments (URLs, ...) or when you are using Secrets like API-Keys. This method will dynamically set the value either retrieved from your environemnts tag or from the operations systems or docker´s environment variables.

ENV(FTP_PASSWORD)

Find details here

LENGTH

The LENGTH(data) method calculates the length of a given string or text. It returns an integer representing the total number of characters in the string.

LENGTH(TEXT(hello))  // Returns: 6

SUBSTRING

The SUBSTRING(value, startindex, endindex) method extracts a portion of a string based on the provided indices.

value: The string or data source from which the substring will be extracted.
startindex: The starting position (inclusive) for the extraction.
endindex: The ending position (exclusive) for the extraction.

SUBSTRING(VALUE(o_line, $.somevalue), 1, 14)

This will extract the substring from the 1st to the 14th character of the string found in $.somevalue in the o_line object.

LOOPINDEX

The LOOPINDEX(ff_name) method returns the current index (starting with 0) of the loop it is used within. This is useful for tracking the iteration number during the processing of fulfillment loops.

ff_name: The name or identifier of the fulfillment loop.

This method is only valid within fulfillment loops.

LOOPINDEX(some_fulfillment_loop)

LIST_BY_VALUES

The LIST_BY_VALUES(text1,test2, ....) method is an easy way to build an array of strings.

ff_name: The name or identifier of the fulfillment loop.

This method is only valid within fulfillment loops.

LIST_BY_VALUES(red,yellow,blue,green) // used in a loop variable this would loop 4 times (array of 4 strings)