Polling API

Polling is Expensive

Running a job on the database to perform operations at End of Day (EOD) is a scheduled operation. If the job is scheduled we can time our calls. Typically schedulers are not ran at peak hours. The difference between polling and running a scheduler is that polling for information does not timed. Polling does not know the state of the API server, its peak hours and traffic conditions. On the contrary, polling is expected to be performed at peak hours. Polling at peak hours can lead to timeouts due to network congestions.

Polling needs to be performed at regular intervals. Polling is expensive since 98% of the API calls are wasted.

Polling a Third Party API

Polling a third party API is the only choice, when the API is not under our control. If the API was within clients domain i.e not third-party, the API can implement techniques like long polling, server sent events and web-sockets to push information when available.

Error Handling during polling

Common error that occur during polling are

1. Timeouts: Due to heavy load and network congestions the API server cannot serve all requests. The requests in the queue are timed out. In such a case the client needs to account for these timeouts and prepare for a retry.
2. Error response: Server can send a 5XX error due to changes in the server. Client must log these error messages.
3. Follow Redirect: The client should always implement auto-redirects. Since the API servers can change over time. In this example we will use OKHttp and it follows redirects by default.

Handling Timeouts

In clients like OKHttp and other we can set Timeouts as follows. We are setting connection and write timeout to 20 seconds. But setting the read timeout to 60 seconds.

new OkHttpClient.Builder()
        .connectTimeout(20, TimeUnit.SECONDS)
        .writeTimeout(20, TimeUnit.SECONDS)
        .readTimeout(60, TimeUnit.SECONDS)
        .build();

Error Response

try (Response response = client.newCall(request).execute()) {

    if (!response.isSuccessful()) { 
        int statusCode = response.code();
        //@TODO check the status code and log the message
    }
} catch (IOException ex) {
    //connection error
}

Following Redirects

By default redirects are followed in okhttp. But they can be disabled to ssl and non-ssl urls.

new OkHttpClient().newBuilder()
    .followRedirects(false)
    .followSslRedirects(false)
    .build();

Polling Example in Java 8

We will demonstrate OKHttp as a client library to perform polling. Also perform error handling and retries in case of failure.

The below example uses OKHttp to send GET API poll request. The class is made Runnable to pass it to the schedular. The run method here gets called after every 10 minutes.

import okhttp3.*;
import org.json.JSONArray;
import org.json.JSONObject;

import java.io.IOException;

public class ApiPoller implements Runnable{
    private static final String BASE_URL = "https://api.metamug.com";
    OkHttpClient client = new OkHttpClient();

    /**
    * Use OKHttp to send GET API poll request.
    */
    public int getCount() throws IOException {
        int count = 0;
        Request request = new Request.Builder().url(BASE_URL + "/covid/v1.0/india/count").build();
        try (Response response = client.newCall(request).execute()) {
            ResponseBody body = response.body();
            JSONObject json = new JSONObject(body.string());
            JSONArray array = (JSONArray) json.get("max_count");
            JSONObject firstElement = (JSONObject) array.get(0);
            count = (Integer) firstElement.get("total");
        }
        return count;
    }

    /**
    * This method gets called after every specified duration
    */
    @Override
    public void run() {
        try {
            int count = this.getCount();
            //@TODO Send the count information somewhere else.
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
       ApiPoller poller = new ApiPoller();
       ScheduledExecutorService schedular = Executors.newScheduledThreadPool(1);
       //specify the time duration
       schedular.scheduleAtFixedRate(poller, 0,10, TimeUnit.MINUTES);
    }

}

Avoid polling when callbacks are available

If server doesn't provide a callback API, clients are forced to use polling. Polling in few cases can used when callbacks dont respond in time or server requests fail. A server must provide a status API for the clients to connect to and poll for the result. There is no such thing as a polling API, unlike a callback API.