News: URL services in ACF 1.7.0

To use various APIs from your FileMaker solution, there are some points.

Ability to send and receive data over the internet

We have new functions in ACF called HTTP_GET, HTTP_POST, HTTP_PATCH, HTTP_DELETE and HTTP_PUT that will be discussed in this newsletter. Also, the function HTTP_BASIC_AUTH 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 specially 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 parameters 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 response...
...
...
...
    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"));

...
...

HTTP_PUT, HTTP_PATCH and HTTP_DELETE

Those functions are variations of HTTP_POST, and they have the same parameters. Some APIs require those to be used for some operations.

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 are a couple of functions that go with this data type that make 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>