Build News Headlines Mobile app using Flutter and Data Platform API (Part1)

Overview

This article demonstrates use-cases and workflows for building a mobile application to shows a News headline and story content from the Data Platform. We will create a mobile demo application using the Flutter UI toolkit with a dart programming. We will use dart programming to create a class or library to support the functionality of the Data Platform REST API. The main functionalities that we need to support is a function to get Access Token from the Data Platform server and a function to search a news headline and retrieve news story content from News services.

To create a mobile UI, we will use the Flutter UI toolkit to build the app. Flutter can be natively compiled applications for mobile, web, and desktop from a single codebase. It is a free and open-source Google mobile UI framework that provides a fast and expressive way for developers to build native apps on both IOS and Android. You can also test the app on the Android emulator and ios emulator (macOS).

There are two parts for this article and this one is the first part to demonstrate how to use dart programming to create a class for retrieving News headlines data from RDP News services. The outcome from this article is a Dart library with a sample console app to test the functionality. The class will be used in the Mobile UI which is Part 2 of this article.

Below is a screenshot of the Flutter mobile app page break down by the use-case. We need to create a dart library to support these functions.

Prerequisites

• Understand a basic concept of the Data Platform and its REST API. We recommend you to read the Data Platform API GENERAL GUIDELINES at the first steps. You can also test your Data Platform account with API Playground to understand the HTTP request and response messages the application has to send and receive.

• Install Flutter and Dart. To build and run the sample application, you can follow instructions from Flutter dev page to setup Flutter on Windows or macOS. You also need to install Android Studio as we need to use an Android emulator to test the Flutter app. Please understand the primary usage of the Dart programming language and Flutter. There are many useful articles on the Internet, and you can also learn primary uses of Dart and Flutter from the Flutter developer site.

• Visual Studio Code (VS Code). You can follow the setting from the Flutter Dev Getting start page to add the Flutter plugin to the visual studio code. Then you can use it to create a new project, write the codes, debug and then build and run the app on the emulator.

• A valid Data Platform account with permission to retrieve news headlines and stories from the News services.

Create the Data Platform Manager (RDP Manager)

In order to use the Data Platform REST API, developers can use any programming languages which support the HTTP client library to send an HTTP request according to REST API specification to get the data from particular services. In this case, we will build a mobile application using Google Flutter UI toolkit, therefore, we can use the http client library provided in dart development kit to call a REST API.

We will create a class or library to provide interfaces to support the functionality of the REST API. It will use the dart http library to handle the HTTP requests and responses from the Data Platform server. The library will support the following functionalities on the Data Platform Services.

1. Get OAuth2 access token. This function will manage to get OAuth2 access token from the Data Platform server. We need to pass the username, password, and client id in the Http request message to get the access token. Or we can use a refresh token to get the new access token from the server after the token is expired. The application has to pass the access token to the HTTP request header when calling the REST API to access the resource on the server.

2. Search news headlines. It will return a list of news headlines including its metadata from the News headline service.

3. Retrieve a news story including metadata from a News story service. Users must pass story id associated with the news headline to the function.

Implementations

Please note that we port the application logic to handle the HTTP request and response messages from C# websocket-api example provided on Github.

Let start creating a new dart console app using Visual Studio Code. You can press Ctrl+Shift+p (on windows) and then type 'Dart' and select Dart:New Project as below screenshot.

Select Console Application, and then select Console Application.

It will ask you to provide a project name and select location to generate the project files. Visual Studio Code will create a new console app with sample codes for you. Then you can modify or delete default files and replace it with our codes.

You can download the whole project and source files from Github. It's the project under folder rdp_manager_console_app. You can find RDP Manager class under the folder 'lib/rdp'.

In this article, we will omit some codes and show you only a snippet of codes required to implement the function.

Building RDP Manager class

This class is the main class to manage data and provide interface to retrieve contents from the Data Platform. You can find full source codes from file <project folder>/lib/rdp/rdp_manager.dart. You can find the main interfaces for the class from the following snippet codes.

Add function to get OAuth2 access token

getAuthenticationInfo is a function to get a username, password, and client id from user input and then send a Login request to the token endpoint to get the OAuth2 access token. This is the first method that the application has to call when using the Data Platform services. This is because when you try to access resources on other services, you need to pass a valid access token in the Authorization header of the HTTP request message. Please find more details about the Authorization from Tutorial Page.

The root endpoint for REST API calls is:

Endpoint for Token Service:

Below is a snippet of codes for the implementation of the getAuthenticationInfo interface. It will return data as TokenResponse class which implemented in '<project>/lib/rdp/rdp_message_data.dart. The method uses the http client interface from the dart package so the app has to import the http library.

Create http headers.

Create a JSON request body and pass the username, password, and client id to the message. Users can just pass refresh_token in case that the access token about to expired.

Then use the http client class to send a post message to a Token endpoint to get the new access token.

Process HTTP response message and get access token from the JSON message. Or process to get the error details from the response or exception in case that it fails. And then return TokenResp to the application.

Create a function to get News headlines

Basically a get headlines operation is an endpoint under News Services group(/data/news/v1/) according to the API Docs page.

Get Headlines endpoint

Query Parameters

The user has an option to pass additional query parameters to get specific content related to the keyword in the query. The following parameters are request options.

• query

  The user search query. It supports Analyze operation. Analyze operation computes a tree expression from a user query string. It would break down a user query string into News related entities, then aggregate them into a boolean filtering tree. You can find more details of Analyze operation from the API Docs page.

• limit Limit of headline (default 10, range value: [0, 100])

• cursor The cursor is a pagination cursor that can be used to retrieve information by pages. Two cursors are prev and next depending on the direction in which you want to paginate. Most of our paginated endpoints support a cursors based syntax. Initial search results always return pagination information with all search contexts and can be used in the next page search.

  Here is an example of cursors present in the response of headlines:

Then to get the next page for the same context use cursor value from the initial search:

Sort Order

Support three values:

• New to Old (default)
• Old to New
• Most Read

If the MostRead sort order was selected, you could specify the date range for most read headlines using mostReadDateFrom and mostReadDateTo parameters.

For example:

• If mostReadDateFrom or/and mostReadDateTo is specified, but the sort order is not equal to mostRead, values will be ignored.

• Relevancy

  Three values are supported:

  • Filter on High relevance should return results for just HIGH
  • Filter on "Medium" relevance should result for Medium+HIGH
  • Filter on "All" relevance should result for Low+Medium+HIGH

  For example:

Response Data

The response data is a JSON message containing fields that represent information such as a story id with headlines, text, and metadata; you can find a list of available fields and its usage from APIDocs.

In this example app, we will parse only fields we are interested such as a list of story id and its headlines, and keep it in our data structure so the application can get the list and show it in the UI.

Below is a class NewsHeadlineResp used to hold the News headlines response; we use it to cache the data from the Http response message.

The following codes are implementations of the getNewsHeadlines method. It starts with creating HTTP headers.

Build query parameters. There are two types of options supported by the app for now, that are query and cursor to get next page for the same data context.

And then use http get to retrieve data using headlines endpoints and query parameters.

If success we start parsing JSON message from the HTTP response. Below is a sample of the JSON message for the headlines response. Omit some parts to shorten a message.

The following codes are sample codes the application used to parse the data from the JSON message. It starts from parsing an array of the story under the data node.

Create function to get News Story

Get Story endpoint

Example

Get Story Content

The story can be retrieved in JSON or HTML format. And to select a story format, two options are available:

Set accept header:

• text/html
• application/json

extension

• json
• html

The extension has a higher priority than the header. It means that if, for example, accept header equal to "text/html", but story ID send as sampleStory.json result will be in JSON format. Using html is quite complicated than json format, which provided news story in plain text. You can find more details about the format of Html from the APIDocs page.

Note that our function will support only 'application/json' format, so it accepts only one input, which is a story id.

Same as the function to get news headlines, we create a class named NewsStoryResp to hold data from the response message. And below is a snippet code of the class.

The getNewsStory function starts from creating the header using the same codes as news headlines, and we need to append the story id to the end of the endpoint like the following snippet code.

Then applications need to use the HTTP GET method to retrieve a News Story content.

Last steps, we need to parse the JSON message to get content.

The function will parse only a language tag, headline text, and a news story in plain text format. The whole JSON Message contains a lot of metadata, so it quite long. We will omit unwanted nodes and focus only on the following JSON data.

Story Content

Node inlineData and inlineXml is a different representation of the same data. inlineData is a text representation, inlineXml is a formatted HTML markup which is ready to be used on HTML pages. Anyway, our function will parse content from inlineData node only.

Language

It represents a list of Language in the news content.

Title

Title is a short description of the news.

Below is a snippet of codes that the function used to parse data from the JSON message.

Test the functionality

After creating the three functions, it's time to test and see if it works as we expected or not.

There is the main function implemented in file bin/main.dart. It will start when you run dart command or debug on Visual Studio code.

The application flow starts from the login to the Data Platform server and gets an access token. Then pass a query to getNewsHeadlines. The application will receive a list of headlines with story id. The last steps it will iterate through the list and call getNewStory to get a new content one by one and print to console.

Below is a snippet of codes from the primary function. It starts from setting the Data Platform account and set a query text to search headlines.

Then get OAuth2 Access Token and if it success, start a Timer to get a refresh token.

Next step, pass the Access Token to the getNewsHeadlines function and getNewsStory function to retrieve data from the News service

Running the app

Please download full projects and source files from Github.

There are two folder in the git repository. Go to folder rdp_manager_conosole_app\bin first.

You might need to start Terminal and run pubtool by typing pub get or flutter pub get command to get dependencies required by the project.

Then modify 'bin/main.dart' and change following lines to your RDP account.

and then change the headlinesQuery to a query you want to search in the following line:

Next step run dart application using the following command.

You will see Access Token print to console when the login is successful, and then the application will print the headline followed by story id and start retrieving a story.

Sampel Output

Summary

In this article, we have described how to create a function to get Access Token from Data Platofrm and implement a function to retrieve news headlines and get its story content from a News Services using Dart programming. It also provides a sample code to parse a data returns from the News services. You can add your own method to get additional data from the JSON message.

The library would be used to develop a mobile app in Part 2 of this article. In the second part, we will describe how to integrate the functions from the class with a Flutter UI toolkit to create a Mobile app. Users can deploy the app on android or ios and then use the app to log in to the Data Platform server and retrieve news headlines from user input. Let see the implementation in the second part.

References

• Data Platform.
• Data Platform REST API.
• Data Platform API GENERAL GUIDELINES.
• Dart Tutorial.
• Flutter Document.
• APIDocs
• Build News Headlines Mobile app using Flutter and RDP API (Part 2)
• Example.RDPAPI.Flutter.RDP_News_Headliens_Flutter