Central API examples

Hi,

I had to give some support to folk that wanted to use the ODK Central API to extract data.

I think it would be useful to have some examples for user not so experienced.

Examples for example on how to create a java method to download csv or zip etc...

Example csv

public static void main(String[] args) {
	Client client = ClientBuilder.newClient();
	Response response = client.target("https://*MYCENTRAL*/v1/projects/*projectId*/forms/*xmlFormId*/submissions.csv")
			.request(MediaType.TEXT_PLAIN_TYPE).
			header("Authorization", "Bearer *AUTHTOKEN*").
			get();

	File downloadedFile = new File("\\*PATHTOSAVE*\\submission.csv");
	String str = response.readEntity(String.class);
    BufferedWriter writer;
	try {
		writer = new BufferedWriter(new FileWriter(downloadedFile));
	    writer.write(str);
	    
	    writer.close();
	} catch (IOException e) {
		// TODO Auto-generated catch block
		e.printStackTrace();
	}

}

Example zip

public static void main(String[] args) {
	InputStream inputStream = null;
	OutputStream outputStream = null;
    int responseCode;
    String responseMessageFromServer = null;
    String filePath = null;
	// TODO Auto-generated method stub
	Client client = ClientBuilder.newClient();
	Response response = client.target("https://*MYCENTRAL*/v1/projects/*projectId*/forms/*xmlFormId*/submissions.csv.zip?media=true&%24filter=__system%2FsubmissionDate%20gt%202021-01-01%20and%20__system%2FsubmissionDate%20lt%202021-01-25")
			.request(MediaType.TEXT_PLAIN_TYPE).
			header("Authorization", "Bearer *AUTHTOKEN*").
			get();

	responseCode = response.getStatus();

    System.out.println("Response code: " + responseCode);

    if (response.getStatus() != 200) {
       throw new RuntimeException("Failed with HTTP error code : " + responseCode);
    }
	
    // get response message
    responseMessageFromServer = response.getStatusInfo().getReasonPhrase();
    System.out.println("ResponseMessageFromServer: " + responseMessageFromServer);
    // read response
	inputStream = response.readEntity(InputStream.class);
	try {
		filePath = "\\*PATHTOSAVE*\\submission.zip";
        outputStream = new FileOutputStream(filePath);
        byte[] buffer = new byte[1024];
        int bytesRead;
        while ((bytesRead = inputStream.read(buffer)) != -1) {
             outputStream.write(buffer, 0, bytesRead);
        }
        
        System.out.println("downloaded successfully at " + filePath);
      	} catch (IOException e) {
		// TODO Auto-generated catch block
		e.printStackTrace();
	}
}

Maybe some links to OData Built-in Filter Operations or Built-in Query Functions directly on the page of export submissions and some practical examples on filters:

e.g. I want to filter submission between 2 dates "filter=__system%2FsubmissionDate%20gt%202021-01-01%20and%20__system%2FsubmissionDate%20lt%202021-01-31"

Do you think this kind of info could be directly on https://odkcentral.docs.apiary.io/# or maybe on the forum?

6 Likes

Thanks @aurdipas, it helped me a lot to integrate a date filter to my pgsql-http requests !

2 Likes

Thanks, @aurdipas!

I think it's a great idea to add links and and an example about $filter to the API docs. I've created a GitHub issue here to discuss that further.

For examples of API requests in Java or another language, I think the showcase is a great place.

Relatedly, I have noticed that Apiary includes examples of API requests in different languages. (If you click on an endpoint, then below the attributes list, you can switch from Raw to a language of your choice.) That said, even within a single language, there are multiple ways of sending a request, and I'm not sure that Apiary shows the easiest or most modern way to do so. And as your example shows, some API requests, like downloading a file, are more complicated than others.

Small other example when you need to filter for datetime (including hours,minutes and seconds).
To add the Hour minute and second the format is:

THH%3Amm%3AssZ

where the %3A is the colon encoded, T indicates the time and Z the zone.

Client client = ClientBuilder.newClient();
Response response = client.target("https://*MYCENTRAL*/v1/projects/*projectId*/forms/*xmlFormId*/submissions.csv.zip?media=true&%24filter=__system%2FsubmissionDate%20gt%202021-01-01T14%3A00%3A00Z%20and%20__system%2FsubmissionDate%20lt%202021-01-25T18%3A00%3A00Z")
		.request(MediaType.TEXT_PLAIN_TYPE).
		header("Authorization", "Bearer *AUTHTOKEN*").
		get();
3 Likes

Hi Aurdipas,

Do you have an example on updating the submissions metadata? Tried the samples from API docs but nothing happens. It is almost the same as the Retrieving Submission metadata.

Thanks.

Raymund