Displaying articles via the Joomla API in a Flutter based app built in FlutterFlow

It would be quite an understatement to say that working with API's and FlutterFlow is quite hard. Theres a huge level of understanding required to get the most out of this low code tool. It is worth it though. Persevere and you have an easily maintainable mobile application, with the benefit of the source code should you need it. Fortunately there are tools which can help to make sense of it all. Lets look at an example of an API and how to integrate it with FlutterFlow. Im going to use Joomla which has an API with a complex structure. Specifically I need to get Joomla API content in the form of articles, to display in my mobile app.

The end result – Joomla Articles in a Flutter app

The end result is a very pleasing app, with great performance, and because it is built in FlutterFlow it is really easy to maintain, update, adjust, and add new functionality.

You can't test API calls in the FlutterFlow builder, so the easiest way to debug is to download the code and build and run it on a real device. As soon as you do this all the standard debugging tools for Flutter become available to you.

Below is a Google Pixel 6a which is connected via a USB cable to the host computer. It is making the connections to the Joomla site API over WiFi. You can load the Flutter DevTools on a running app to observe whats going on on your device and you can see from the network tab the details of the API call.

The Title, Image, Image Caption, Summary text, Author and Date modified in the applications user interface all come from separate elements of the API response and are repeated for each article using a listview and dynamic children. There is also a FlutterFlow custom function in Dart which turns the date returned from the Joomla API into a better readable human date to display on the Card a bit more like how it would be presented in Joomla on the website.

Joomla API in a Flutter app

TL:DR — With patience you can build powerful apps using Joomla as a backend to FlutterFlow underpinned by the Joomla API.

Adding the Joomla API to your FlutterFlow project.

You can read about the Joomla Articles API call in the Joomla Core APIs documentation but thats for another time. This is all about matching up the FlutterFlow API call settings to the requirements of the Joomla API.

Define an API Group

• Choose API in FlutterFlow builder (may be dependent on the plan you have for FlutterFlow)
• Create an API group and give it a name,
• Set the API base URL that all the API calls in this group will use,
• Add the required headers, for Joomla this required Content-type: application/json and Accept: application/vnd.api+json,
• In Advanced settings I left Proxy for test set, but not for run/test mode as I am using real devices for testing (and so should you, because you cannot test API calls in run/test modes in FlutterFlow).

Defining the Joomla Articles API

You really do need to think carefully about naming and details here as they will matter for making sure you can understand any issues you encounter. FlutterFlow provides a tremendous toolset to make this easier to navigate than code, but it doesn't change the concepts which still need to be organised well to make sense.

• Define an API Call, give it a name, I just chose Articles, to make it easy to understand in FlutterFlow, as it is the last part of the name of the API endpoint,
• Set the Method Type that this API call will use, the Articles API call from Joomla uses GET you'll see that the API base URL is already set from the API Group.
• Set the full API endpoint which is /api/index.php/v1/content/articles.
• Save

Testing the Joomla Articles API

• Select 'Response & Test',
• Press the 'Test API Call button.

Successful testing of the Joomla Articles API

If you see the resulting API call body JSON data and a Status: 200 (Success) message you now know that your API correctly returns a Body JSON response from your API and can congratulate yourself on having set up your API group headers and this first API call correctly. But theres still a lot to do to use the data from this API response to your FlutterFlow app.

Making JSON response data useful in your FlutterFlow app

There are two approaches to making the data useful from your API response in your FlutterFlow app.

1. The first approach is to use JSONPath expressions, which are powerful but as complex to debug as spreadsheet macros.
2. The second approach to map the API data to a set of custom Data Types which provides a consistent, and less error prone structure.

Both of these approaches and mixing them together are well supported in FlutterFlow.

Using JSONPath to find content from API results

JSONPath expressions are a path expression syntax for addressing portions of any JSON structure. So for a single Joomla article you might want to find the title. The path expression you need for that is $.data.attributes.title and it means find the JSON element called data, then inside it find the element called attibutes, and then return the content of title. JSONPath expressions are easy to work with and test and FlutterFlow can create example JSONPath expressions for your API.

However, for an API like the Joomla articles APi which returns more than one article, JSONPath expressions quickly get complex. The JSONPath for listing the ID's of all the articles returned would be $.data[:].attributes.id because you are looking at multiple items as denoted by the [:].

JSONpath is terse and if you are planning to use it it is worth pasting valid API responses into tools to play with what you can do. Theres an excellent tool for doing this which is the JSONPath Online Evaluator - jsonpath.com. You can paste an example of your API response and type JSONpath expressions ansd see the results intantaneously.

Using FlutterFlow to find JSONPath expressions from API results

A list of recommended JSONPath expressions are provided in FlutterFlow once you test an API response. You can name these for use in your FlutterFlow app, or just use the JSONPath expression directly in FlutterFlow.

This is incredibly useful in getting to grips with JSONPath expressions for your API.

Using Custom Data Types to structure the content from the API results

Custom Data types are hard to understand. They provide a structure for you to use in FlutterFlow in choosing the right data to show in your app. Custom Data types let you define any structure (in this case a list of Joomla articles) so that your FlutterFlow based app can make sense of it. 

Under the covers they look like classes which is a somewhat scary term for many but helps me make sense of them for FlutterFlow. Custom Data types in FlutterFlow have to be set out very precisely and it is important to carefully check them otherwise your app will fail with odd data type errors which are hard to debug. One added complexity is that Data Types can be nested. That is to say a Data Type entry can contain another Data Type. The Joomla articles API is an example of an API which needs this kind of structure. Attributes is inside Data in the structure.

One effective way which saves hours of work to map a complex API to a Custom Data type is to use an online tool to help you determine the correct data type and structure for each field being returned from your API. 

Using quicktype.io to help you determine your data types

• Head over to quicktype.io 
• Paste your API response JSON into the left column.
• Set the language to Dart if it isn't already and your classes will be created. These are going to be used as the basis for FlutterFlow Custom Data Types.
• You can see the Attributes class in Dart created from the attributes element of the JSON in the screenshot.

Thats pretty cool. The input JSON data has been used to create a class for each of the elements. You can use this class information to populate your Custom Data Types in FlutterFlow. But you need to do this with care and not assume it it 100% correct because it is not. Also and very importantly you still need to correctly establish the structure for the nesting of the data types in FlutterFlow.

Creating Custom Data Types in FlutterFlow

Start at the deepest nesting level of your hierarchy, take the images element for example. thats one of the deepest levels, so lets start there. The images element looks like this in our converted Dart class, its the data type on the left that we are interested in:

class Images {
    String imageIntro;
    String imageIntroAlt;
    String floatIntro;
    String imageIntroCaption;
    String imageFulltext;
    String imageFulltextAlt;
    String floatFulltext;
    String imageFulltextCaption;
...

To add the images Data Type from the Joomla Articles API to FlutterFlow:

• Select DataTypes in FlutterFlow and add a data type called Images.
• CLick on 'Add Field' and add each original fieldname from the API not from the class definition. We're only interested in the data type and the structure.
• Images have their own FlutterFlow data type of Image Path, so even though they are String in the class defintion above they need to be Image Paths in FlutterFlow. 
• But still even in this simple example it is an easy workflow. 

The reason for adding the images Data Type first is because it is needed in the Attributes Data Type in order to represent the structure of the Joomla Articles API to FlutterFlow:

• Select DataTypes in FlutterFlow and add a data type called Attributes.
• Click on 'Add Field' and add each original fieldname from the API not from the class definition. Again we're only interested in the data type and the structure.
• Add the images as the Data Type Images that you created above.
• Now you have a Data Schema with a Data Type containing a nested Data Type.
• Dates in Joomla are strings to FlutterFlow, so even though they are DateTime in the class defintion above they need to be Strings in FlutterFlow. 
• Even with this more complicated example this is still an easy workflow.

Repeat this process for all the structures in your API which have been conveniently put into classes in quicktype.io.

• Select DataTypes in FlutterFlow and add a data type called Data.
• Click on 'Add Field' and add each original fieldname from the API not from the class definition. Again we're only interested in the data type and the structure.
• Add attributes as the Data Type Attributes that you created above.
• Now you have a Data Schema with a Data Type containing a nested Data Type which contains a nested Data Type.
• This nested Data Schema is complicated, but it represents the API properly, and was, I think, easier to comprehend by using some helper tools to understand it.

Once completed you can go back to the App Screens and add API calls.

Displaying Joomla articles in your FlutterFlow app

All this work has to pay off. Now we can get Articles from Joomla to appear in FlutterFlow. I've created a page for the articles and using the page builder I have added a ListView which is where the API call is made. the ListView contains a Card containing the Widgets needed to display the API content. It looks like this:

Joomla Articles in a ListView in a Page in FlutterFlow

You can see on the page from the icons to the right of the ListView that the ListView control has a backend query, and is set to generate dynamic children. This is exactly what is required to display a list of articles from Joomla.

Creating the backend query

The ListView backend query uses the API Group and API endpoint name Articles that was set up earlier

Then the children are generated from a variable apiArticles set to the Articles API response as data structure field data from the Articles data structure. This is our list of Joomla articles, with the response as Data Structure fields rather than JSON.

Successful conclusion - App published

You can build seriously complex apps with FlutterFlow, but the complexity still needs to be understood and in the case of the Joomla API this was achieved through effective use of Data Types and JSONPath syntax in order to bring the API data into the app design.

The app passed App Review and Google Play Store review hours after being submitted for publication.

See also

• quicktype.io – Convert JSON into gorgeous, typesafe code in any language
• jsonpath.com – JSONPath Online Evaluator
• jsonapi.org JSON:API – Pay particular attention to MIME Types