← Back to blog
Sunday, December 20, 2020

What is the Reporting API?

Many things happen on a web browser that is not visible on the server. We don't want servers to know everything, otherwise, it could be a serious privacy concern as well as a noticeable performance hit. Yet there are a few things in which it'd be helpful to know so that web administrators can take appropriate actions.

Reporting API is a recent specification from the W3C performance group, it describes a standard as to how browsers should send various reports to a server.

This is the foundation on which other browser features will rely to share reports with a backend. These reports follow a well-defined structure in JSON and are sent via HTTP POST, so it's fairly easy for backends to ingest them.

This is an example of a Network Error Logging report.

{
  "type": "nel",
  "age": 42,
  "url": "https://example.com/thing.js",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
  "body": {
    "referrer": "https://www.example.com/",
    "server_ip": "234.233.232.231",
    "protocol": "",
    "status_code": 0,
    "elapsed_time": 143,
    "type": "dns.name_not_resolved"
  }
}

That's useful information, isn't it? This JSON is telling us that someone using Firefox in Linux had a DNS issue whereby it was unable to resolve the name www.example.com.

How to get started

To enable it, a new HTTP Header named Report-To must be set. An example using RepointHub as the endpoint would be:

Report-To: {"group":"default","endpoints":[{"url":"https://yoursite.ingest.repointhub.com/report"}],"max_age":86400,"include_subdomains":true}

Report-To has been recently renamed to Reporting-Endpoints, so it's recommended to set both headers for best compatibility. The new header expects a slightly different format:

Reporting-Endpoints: default="https://yoursite.ingest.repointhub.com/report"

By adding these headers we're telling browsers to send reports to https://yoursite.ingest.repointhub.com/report. Reports are sent out-of-band with website activity so that it does not impact the user's activity.

Some report types (such as NEL) requires further configuration (which is just another HTTP Header) before it can be activated, but other reports like Crashes, Depredations and Interventions are automatically collected when there is an endpoint named default.

Is your website configured for Reporting?

Use the following form to check.

The future of Content Security Policy reporting

CSP is a popular feature that has defined its own reporting mechanism, using the report-uri directive. The latest CSP specification is now transitioning to Reporting API, which is another great step forward towards having a unified reporting framework.

Conclusion

Data to power decisions. That's essentially what we can expect from this specification. The more information people can get directly from our client's browser, the better actions they can take to improve their services.

There is also an extensive topic around privacy so that this report does not end up exposing anything that it should not. End users can rest assured, their privacy is not compromised.

This is just the beginning and we can expect a lot more browser features to start adding support for it going forward.

Although the spec is still a work in progress, Chrome, Edge, and a few other Chromium-based browsers have already added support, which means there are enormous benefits of having this enabled right now!

We can be your report collector so you don't need to build your own. Sign up for a free trial of RepointHub to get started.Try it free now!