In a nutshell

curl
    -X POST
    --header "Content-Type:application/json;charset=UTF-8"
    --user "YOUR API KEY:"
    -d "YOUR JSON DATA"
    http://gateway.flashreport.io/api/v1/report/new

The return value is a unique identifier representing your report creation request. You use this identifier in the various API endpoints described in this page.

Basic concepts

Once you have registered with FlashReport.io, you request the creation of reports by sending HTTP requests to our servers. These requests can be issued from systems written in many development languages, such as Java, .NET, javascript, php... The only condition is that your language must be able to send HTTP requests with basic authentication. This is the case for most modern languages.

You send us a HTTP request with data. That data is the structured information you want to turn into a report. At the moment we support data in the JSON and XML formats, and generate PDF documents. We reply with a unique identifier representing your request, in a RESTful way.

cURL samples

cURL is a command line tool and library for transferring data with URL syntax. We use it in many examples on this page because it's easy to use and allows you to explore FlashReport API's without having to write a single line of code.

If you do not have cURL already installed on your system, you can download it from this page.

API security

All flashreport.io APIs require authentication. We use an API key (also called API token) and basic authentication. To get your key, log in to the dashboard and go to the control panel screen. Click on an active subscription to get your API key.

Our APIs are exposed in HTTP and HTTPS. HTTP should only be used for simple tests, e.g. with cURL tests to explore the API. For production use, we strongly recommend that you use HTTPS.

Report creation

To request the creation of a report, you send us a HTTP POST request containing your data. For example, let's assume you want to generate a report based on the following JSON array

[
    {
    "component name": "Cooling circuit valve H567",
    "date": "01/01/2015", "purged": false, "throughput": 180
    },
    {
    "component name": "Cooling circuit valve H567",
    "date": "02/01/2015", "purged": false, "throughput": 170
    },
    {
    "component name": "Cooling circuit valve H567",
    "date": "03/01/2015", "purged": true, "throughput": 210
    },
    {
    "component name": "Cooling circuit valve H567",
    "date": "04/01/2015", "purged": false, "throughput": 131
    },
    {
    "component name": "Cooling circuit valve H567",
    "date": "05/01/2015", "purged": false, "throughput": 138
    },
    {
    "component name": "Cooling circuit valve H567",
    "date": "06/01/2015", "purged": true, "throughput": 165
    },
    {
    "component name": "Cooling circuit valve H567",
    "date": "07/01/2015", "purged": false, "throughput": 117
    }
]

Let's assume that information is in a file named 2015w1.json.
The cURL command to request the generation of the report is as simple as

curl
    -X POST
    --header "Content-Type:application/json;charset=UTF-8"
    --user "YOUR API KEY:"
    -d @2015w1.json
    http://gateway.flashreport.io/api/v1/report/new

You can see the generated PDF document here.

Let's decompose that command:

curl
1 -X POST
2 --header "Content-Type:application/json;charset=UTF-8"
3 --user "YOUR API KEY:"
4 -d @2015w1.json
5 http://gateway.flashreport.io/api/v1/report/new

1 indicates we are doing a POST
2 this header specifies we are sending JSON encoded with UTF-8. FlashReport only supports UTF-8.
3 use basic authentication with your API key as username and no password (hence the trailing colon)
4 the data to send, with @ to reference a file. You can also omit the @ and put your JSON between quotes
5 the URL to create a new report. Remember to use HTTPS for any production use.

Handle the response

The result of the report creation POST command, if successful, is a 201 HTTP response containing a UUID, such as fc4159fa-0e95-48c2-8cd4-0be041f4212f.

You can use that UUID to get the status of your report. Just append your UUID to the report endpoint. For example:

https://gateway.flashreport.io/api/v1/report/fc4159fa-0e95-48c2-8cd4-0be041f4212f

Alternatively, you can use the location header of the response with contains the URL of your report.

You can also use a browser, just use your API key when prompted for a user name. Leave the password empty.

Tip : to get a nice layout like in the above screen capture, use a browser extension such as JSONView for Chrome

reportUuid this is the unique identifier (UUID) for your report
creationRequestDate indicates when flashreport.io received your request.
availabilityDate indicates when the report was generated
state can be GENERATING, GENERATED, or FAILED
title is the title you specified for this report, if any
payloadUrl is a URL where you can consult the payload we received for this report. This is mostly for debugging purpose.
logUrl is a URL where you can consult generation log for this report. This is mostly for debugging purpose.
downloadUrl is a URL where you can download your report. It redirects you the the actual download URL
storageUrl is a URL where your report is stored. It differs from the downloadUrl because it does not redirect you, it just return the URL to use.

Download URL usage
Please note that the URL to download your report is a presigned Amazon S3 URL. You should not use any credentials to access that URL. Also, it has a limited validity in time of about one hour. This is not an issue with the /downloadUrl endpoint because it will immediately redirect you to the S3 URL. However, the /storageUrl end point does not automatically redirect you, so you should not wait too long before using the S3 URL it returned. Of course, you can always request a new presigned, temporary S3 URL by invoking the /storageUrl endpoint again.

Specify a title

You can if you want specify a title for your report. It will appear in the dashboard, and the name of your PDF file will end with that title.

curl
    -X POST
    --header "Content-Type:application/json;charset=UTF-8"
    --user "YOUR API KEY:"
    -d @2015w1.json
    http://gateway.flashreport.io/api/v1/report/new?title=2015Week1

Specify a template

You can register templates in the Templates section of the dashboard. You select a JRXML file and define a unique identifying name for that template. You can then specify that you want to use that template for a report generation. Of course, you must make sure that the template is compatible with your data. We recommend that you use Jaspersoft Studio to design your template and test it with your data file.

curl
    -X POST
    --header "Content-Type:application/json;charset=UTF-8"
    --user "YOUR API KEY:"
    -d @customers.json
    "http://gateway.flashreport.io/api/v1/report/new?title=CustomersByCountry2015Q1&template=customers"

For reference, you can consult the template, the data source file, and the resulting pdf.

Handle errors

Invalid subscription

If you subscription is not valid, for example because you do not have setup payment information at the end of your trial period, your report generation requests will be refused. To see the status of your subscription, go to the control panel and look at the Valid until column.

{
    "timestamp":1426255250685,
    "status":401,
    "error":"Unauthorized",
    "message":"Bad credentials",
    "path":"/api/v1/report/new"
}

Payload too large

The plan you select determines the maximum payload size we can handle. If you try to generate a report from a payload which is greater than the maximum payload size of your plan, your request will be refused and you will receive a 413 Request Entity Too Large response code.

Maximum number of reports

The plan you select determines the number of reports you can generate per month. If you try to generate a report when you have already reached your monthly limit, your request will be refused and you will receive a 429 Too Many Requests response code. You can see how many reports you have generated for the current monthly period in the control panel.

Code samples

Please check our GitHub account for complete, running samples!

Java with HTTP client from Apache

public void runHttpClient() throws Exception {

    String reportTitle = "Requested by HtttpClient";
    String url = new URI("https", "gateway.flashreport.io", "/api/v1/report/new", "title=" + reportTitle, "")
    .toURL().toString();

    // Setup credentials for the host
    CredentialsProvider credsProvider = new BasicCredentialsProvider();
    credsProvider.setCredentials(
    new AuthScope("gateway.flashreport.io", 443),
    new UsernamePasswordCredentials(API_TOKEN, ""));

    // Use them to build the client
    CloseableHttpClient httpclient = HttpClients.custom()
    .setDefaultCredentialsProvider(credsProvider)
    .build();

    // Post the generation of new report
    HttpPost httpPost = new HttpPost(url);
    httpPost.setEntity(new StringEntity(readTestMessage("SimpleTest.json")));

    // Log result
    try (CloseableHttpResponse response = httpclient.execute(httpPost)) {
        logger.info(String.format("Response status code : %s", response.getStatusLine()));
        org.apache.http.HttpEntity entity = response.getEntity();
        logger.info(String.format("Response body : %s", EntityUtils.toString(entity)));
        EntityUtils.consume(entity);
    }
}

Java with Rest template from Spring

public void runRestTemplate() throws Exception {

    String reportTitle = "Requested by RestTemplate";
    String url = BASE_URL + "/new?title=" + reportTitle;

    // Setup HTTP header with BASIC security
    HttpHeaders httpHeaders = new HttpHeaders();
    String basicHeader = "Basic " + Base64.getEncoder().encodeToString((API_TOKEN + ":").getBytes());
    httpHeaders.add("Authorization", basicHeader);

    // Post the generation of a new report
    RestTemplate restTemplate = new RestTemplate();
    HttpEntity entity = new HttpEntity<>(readTestMessage("SimpleTest.json"), httpHeaders);
    ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, entity, String.class);

    // Report creation response
    logger.info(String.format("Response status code : %s", response.getStatusCode()));
    logger.info(String.format("Response body : %s", response.getBody()));

    // Query report status URL
    String reportUuid = response.getBody();
    response = restTemplate.exchange(BASE_URL + "/" + reportUuid, HttpMethod.GET, new HttpEntity<>(httpHeaders),
    String.class);

    // Report status response
    logger.info(String.format("Response status code : %s", response.getStatusCode()));
    logger.info(String.format("Response body : %s", response.getBody()));
}