Api asyrrestcli

This library gives access to functions used to perform outgoing REST web services.

This function is not available in version 7.0 used for early adopters, but will be delivered in version 7.1 and higher.

Func EXEC_REST_WS

This function is used to call an external REST web service that has been configured in the Administration Reference Outgoing REST Web services administration page.

It works on a function called either in Classic mode or in native version 7 mode, and returns the HTTP status of the operation.

The parameters are described below:

Code	Type and dimension	Contents
NAME	Value Char	The name of the [web service definition](../administration-reference/outgoing-rest-web-services.md).
HTTPMETHOD	Value Clbfile	The HTTP method used (can be GET, PUT, POST, or DELETE).
SUBURL	Value Char	The service called in the REST web service. It is a sub-URL that appends to the main URL of the service.
PARAM_COD	Value Array of Char	Additional property names that can be used as URL parameters.
PARAM_VAL	Value Array of Char	Additional property values corresponding to property names defined in PARAMS_COD.
HEADER_COD	Value Array of Char	Additional property names that can be sent in the request header as parameters.
HEADER_VAL	Value Array of Char	Additional property values corresponding to property namea defined in HEADER_COD.
DATA	Value Clbfile	The data that is sent with POST and PUT methods.
FUTURE	Value Integer	If 1, the web service is called in 'future' mode; if 0, the 'wait' mode is used.
RETURNS	Value Char	If empty, the whole JSON feed is returned in RESBODY; if not empty, only the value of the corresponding property is returned in RESBODY.
RESHEAD	Variable Clbfile	The response header returned by the web service.
RESBODY	Variable Clbfile	The response body returned by the web service.

Comments

Data format

The data sent to the web service must be in JSON format, but can either be sent as a string value containing the stringified object, or sent as an object in a string. It can be sent as a data by using the following code:

{
  "firstName" : "John",
  "name" : "Doe",
  "age" : 25
}

This data can be sent by assigning:

DATA='{"firstName":"John","name":"Doe","age":25}'

or

DATA='"{\"firstName\":\"John\",\"name\":\"Doe\",\"age\":25}"'

Parameters and Header parameters

These parameters can be defined by default in the web service administration page. When some parameters are defined at calling time, the values sent will replace the corresponding parameters values if they were defined by default, and/or complete the parameters value list.

The parameter sent in PVAL and HVAL must be sent as JSON constant. This means that if the first value is the logical `true` value, the second is a string containing `true`, and the third a date (for example, the 14th of July 2014), and the fourth a number (for example, 3.1415926), the assignment lines will be the following:

CODECODE CODEsh
  PVAL(1)="true"         : # Logical constant
  PVAL(2)='"true"'       : # String constant (between quotes)
  PVAL(3)='"2014-07-14"' : # Date constant (between quotes)
  PVAL(4)="3.1415926"    : # Numeric constant

Examples

CODECODE CODEsh
# Call of a web service that only gets data
# The web service is called with the sub-URL "prices/ITEM_CODE"
# if returns a JSON that is: {"item":"ITEM_CODE","price":PRICE_VALUE}
Funprog PRICE(ITEM)
Value Char ITEM()
Local Integer RETVAL
Local Decimal PRICE
# No additional parameter nor additional header value are given here (only the values given in ORDER definition are used)
Local Char PCOD(100)(1..10),PVAL(100)(1..10),HCOD(100)(1..10),HVAL(100)(1..10)
# Contains the result header and body
Local Clbfile RESHEAD(0),RESBODY(0)
# Call the web service and get only the "price" value
  RETVAL=func ASYRRESTCLI.EXEC_REST_WS(
&        "ORDER","GET","/prices/"+ITEM,PCOD,PVAL,HCOD,HVAL,"{}", 0, "price",RESHEAD, RESBODY)
  If RETVAL=200 : PRICE=val(RESBODY) : Else PRICE=0 : Endif
End PRICE
# Call a web service that posts an order in an external system
# uses "/order/" sub-URL, requires an user id sent as a parameter ( &USERID=myuid )
# "This" is an instance that has the following properties:
#  - CUSTOMER,ORDDATE,ORDNUM,CURRENCY, TAXES
#  - an array of LINES instances having the following properties: ITEM, QUANTITY, PRICE
$SEND_ORDER
Local Char PCOD(100)(1..10),PVAL(100)(1..10),HCOD(100)(1..10),HVAL(100)(1..10)
Local Clbfile RESHEAD(0),RESBODY(0),CDATA(0)
Local Integer I
Local Char SEP(1)
# Add a parameter
PCOD(1)="USERID"
PVAL(1)='"'+GACTX.LOGIN+'"'
# Add two header parameters (it would probably be better to define them in the web service definition)
HCOD(1)="Accept-Language"
HVAL(1)='"fr, en-gb;q=0.8, en;q=0.7"'
HCOD(2)="Accept"
HVAL(2)='"application/json"'
# Fill CDATA
  CDATA="{"
  CDATA+='"ORDNUM":"'+num$(this.ORDNUM)+'",'
  CDATA+='"CUSTOMER":"'+this.CUSTOMER+'",'
  CDATA+='"ORDDAT":"'+format$("D:4Y[-]2M[-]2D",this.ORDDAT)+'",'
  CDATA+='"CURRENCY":"'+this.CURRENCY+'",'
  SEP="" : CDATA+='"LINES":['
  For I=1 to maxtab(this.LINES)
    If this.LINES(I)<>null
       CDATA+=SEP+'{"ITEM":"'+this.LINES(I).ITEM+'",'
       CDATA+='"QUANTITY":'+num$(this.LINES(I).QUANTITY)+','
       CDATA+='"PRICE":'+num$(this.LINES(I).PRICE)+'}'
       SEP=","
    Endif
  Next I
  CDATA+='],"TAXES":'+num$(this.TAXES)
  CDATA+="}"
# Call the web service and get only the "price" value
  RETVAL=func ASYRRESTCLI.EXEC_REST_WS(
&        "ORDER","POST","/order/",PCOD,PVAL,HCOD,HVAL,CDATA, 0, "",RESHEAD, RESBODY)
# Manage the errors
  If RETVAL<>200
    [L]ASTATUS=fmet this.ASETERROR("","Post failed status="+num$(RETVAL),[V]CST_AERROR)
  Endif
Return