Migrating to Version 3 of the API

In October 2022 we launched Version 3 of the WhatIsMyBrowser.com API. This document outlines the reasons for the new version, the changes, and how you need to modify your system's code to work with the new version.

The reason for the new version

There have been some big changes recently in the world of web browsers, relating to the way browsers can be identified. Until recently, you could identify the browser, OS, device, (etc) that someone was using, simply by sending your visitor's User Agent String to the API.

However, with the introduction of Client Hints to Chromium-based browsers, and with a number of web browsers minimizing or "freezing" the information in their user agent strings, accurate browser detection now relies on more than just analysing User Agents.

With the switch to using more than just User Agents to perform browser detection, we made the decision to leave User Agent Parsing in Version 2, and create Version 3 which takes a broader and more future proof approach to browser detection.

Version 3 analyses all HTTP Headers for more detailed and accurate results

The new Version 3 of the API looks at all the HTTP Header values (focusing on both the User Agent and Client Hints headers) from your site visitors to more accurately detect what your visitors are using.

Analysing all HTTP Headers also allows for better fraud and risk detection

It's still very common for bots and scripts to impersonate real traffic and browsers just by faking their user agent header; or for a user to change their user agent string in their browser. But since we're looking at all their headers, unless they've taken extra special care to fake all of their HTTP headers, we'll be able to identify the discrepancies between what their headers are and should be.

Version 2 remains available for those who need to work with User Agents specifically

User Agents aren't going away any time soon though, and Version 2 will continue to exist and be operational for all your User Agent related needs. Parsing, Batch Parsing, and Downloading or Searching the Database of User Agent strings will all remain operational, but won't be included in Version 3.

• If you need to detect the Browsers, Bots, and technology your visitors are using to access your site, use the new Version 3 API.
• If you need to specifically parse user agents, or search for groups of user agents that match certain criteria, you'll need to use Version 2 for that.

The User Agent Parser continues to be developed

A significant part of the new Version 3 of the API still relies on parsing User Agents, so the User Agent Parsing features of Version 2 will still continue to be developed and maintained. In other words, even as we work on the new, all encompasing Version 3 Browser Detection, it will also further improve the user agent parser too.

Who is this migration guide for?

This is for customers who use the API to detect the browsers, operating systems, devices, hardware, and so on that your visitors are using: you are encouraged to follow this guide to switch to Version 3.

If you really do need to just parse user agents or work with the database of user agents, then you can certainly keep using the older Version 2 end points.

---

Retired end points

The following API end points were in Version 2, but aren't in Version 3. They remain operational, so if you need to, you can still keep using them.

All the user agent related end points are being retired

User Agent Parse

The API User Agent Parse end point has been retired and replaced by Version 3's "Detect" end point.

If you still have a use-case for decoding user agent strings then you can still keep calling the User Agent Parse end point with those user agents - We will keep developing the user agent parser library and new detection will continue to be added for it, but for general "browser detection" you should be looking to the new Version 3 "Detect" API End point for all your browser detection needs.

User Agent Batch Parse

For much the same reasons that we are retiring the Parse end point, we are also retiring the User Agent Batch Parsing end point.

And in the same way too; if you still have a database or log file of user agents you need to decode, then you can still always access the Version 2 batch parse end point with them, but there won't be something like this in the new version of the API.

User Agent Database Downloads & Search

As discussed, user agent strings - by themselves - are being left in the past, and so the user agent string database is going to be less and less useful. Since everything related to User Agents is staying in Version 2, it's only fitting that the database downloads and search remain here too; the database won't be available in Version 3; if you still need to search or download it, use the Version 2 end points.

Making the required changes

There are a few things that need to change on your end to switch to Version 3. None of these are big departures from the way that Version 2 did things. In short you will need to:

• Request that your visitor's browsers send you their Client Hints. You do this by adding the necessary Client Hints HTTP Response Headers to your visitors. This will cause Browsers that support Client Hints to start sending Client Hints Headers to your site
• Gather and send all of the HTTP Request Headers (including the Client Hints HTTP Headers) that their browsers send to your site
• There are some changes to the response format from the API

Lets go over these in detail:

Request that your visitor's browsers send you their Client Hints

Browsers will normally only send a fraction of the Client Hints headers that they're capable of sending, unless your server requests that they send them all. You need to modify the HTTP headers in your Server Responses to include two new headers: accept-ch and critical-ch.

Rather than repeating ourselves, you can find the full values for those headers in the Integration Guide on the Detect Requests page.

Gather and send all of the HTTP headers that your visitors send to your site, to the API

Version 3 of the API no longer uses just the User Agent header, it works best when you send all the HTTP headers from your visitors to it. This helps us identify people and bots visiting your site who are faking their user agents.

Changes to the response format from the API

The API response in Version 3 is very similar to the response from Version 2. There are a few differences that you will need to adapt to:

• The name of the JSON key that holds the detection response has changed from parse to detection, to reflect that we are now doing more than just parsing a user agent.
• The Software Version check data, which used to just live in version_check, is now nested under software_version_check. This is so that it more accurately reflects that the version checking is being done for the software (ie. The Web Browser). We plan to include Operating System Version Checks in the future, so doing this provides separation/space to add it in the future
• The is_weird, is_abusive (etc) fields aren't under the detection/parse response, they now have a seperate key called risks. So far, we group the risks under user_agent_risks and client_hints_risks. We plan to increase the number of risk checks for user agents and client hints, as well as to add entire new classes of risk analysis. When we do, that's where they will be found.
• The message_code in result has changed from user_agent_parsed to detection_processed

Hopefully these changes aren't too much of a hassle for you to make. If you ever need help, just get in touch.

Welcome to the new version of the API!