News: URL services in ACF 1.7.0

To use various API's from you FileMaker solution, there is some points.

Ability to send and receive data over the internet

We have the new functions in ACF called HTTP_GET and HTTP_POST that will be discussed in this newsletter. Also, the function HTTPBASICAUTH lets you create the authentication you need for accessing password-protected sites.

Ability to Format the data packages to send

To post data to an API, you need various tools to format the data in the specifications for that API. Various formats like HTTP_FORM, XML, or JSON are most widely used. We will discuss this in this newsletter

Ability to parse the response from the API

When interacting with APIs, the purpose is to send updates to the other party or retrieve data from the API. All APIs give some response back that needs to be parsed. Usually that can be a special formatted clear-text response, an XML response, or a JSON response. We will also discuss this in this newsletter.

Sending data over the internet.

Most APIs use the HTTP protocol to send data, like POST or GET to the web service. The two functions here make that easy. The API specifications tell if it is a POST or GET that should be applied. The system variable called HTTP_STATUS_CODE contains the last status code and can be examined. The normal value is 200.

HTTP_POST

The HTTP_POST function in ACF sends a post to the API. The parameters are:

The URL ( WEB address for the service )
The POST DATA
Optional headers, each separated by a \r, like Content-Type: text/xml
Optional authentication header. We can use the function HTTP_BASIC_AUTH to generate this header for this parameter if that is the authentication method. It can be included in the headers parameter too, but for simplicity, we have added this as a fourth optional parameter.

Example:

Function UpdateWebService ()
    string post_data = "Here is the prepared post data we send to the web-service"; 
    String response = HTTP_POST ( "https://example.com/webService/", post_data,
        "Content-Type: text/plain", HTTP_BASIC_AUTH("ole", "dole")); 

    if ( HTTP_STATUS_CODE = 200 ) then
// Do the parsing of the response....
...
...
    else
        return "Some Error, " + response; 
    end if
End

HTTP_GET

HTTP GET is mostly used for APIs that do not need much input, but retrieve data from the API. The URL contains the paramters to send, and we get the data in the response.

The parameters are:

The URL (with parameters encoded)
Optional headers, each separated by a \r
Optional authentication header.

Example:

Function GetDataFromAPI ()

    string url = format('%s?Year=%s&month=%s', "https://example.com", "2023", "11");
    string response = HTTP_GET ( url, "", HTTP_BASIC_AUTH("ole", "dole"));

    if ( HTTP_STATUS_CODE = 200 ) then
// Do something with the responce...
...
...
...
    else
        return "Some Error, " + response; 
    end if

End

URL encoding

Some parameters in the URL can have values that are not compatible with the URL, like spaces or special characters. They need URL encoding. To do that, we can use the function URL_ENCODE that returns the encoded parameter. Like this.

string textpar = URL_ENCODE ( "This is the parameter that needs 
encoding, because of Line break, The ?, / and other" ) ; 

string url = format('%s?Year=%s&month=%s&text=%s', 
                "https://example.com", "2023", "11", textpar);

string response = HTTP_GET ( url, "", HTTP_BASIC_AUTH("ole", "dole"));

...
...

XML data used in the APIs

Often, an API requires some XML-formatted data as input. For this, we have defined XML as a new data type in ACF. There is a couple of function that goes with this data type that makes both the creation of XML objects and parsing XML objects a breeze.

This example shows how easy it is to create an XML document.

    XML xmlvar;
    xmlVar["MyRootNode.User"] = 
            XML("Name","John Doe","Address","Road 2");
    // Assign attributes to the XML...
    XMLattributes(xmlVar["MyRootNode"], XML("xmlns:ns","https://mynamespace.com/test/");
    XMLattributes(xmlVar["MyRootNode.User"], XML("UserID","20031");
    
    print string(XmlVar);


// This will produce
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<MyRootNode xmlns:ns="https://mynamespace.com/test/">
<User UserID="20031">
    <Name>John Doe</Name>
    <Address>Road 2</Address>
</User>
</MyRootNode>