How API Clients Should Set Their User Agent

Any program making HTTP requests sends a user agent, whether or not its author thought about it. Setting it deliberately is a small effort that avoids a recurring class of problems.

The default reveals only the library

An unmodified client sends the name and version of the HTTP library. That identifies the tool, not the software using it or the party responsible for it.

To a server operator, one library default is indistinguishable from any other program using the same library, including whatever is currently causing problems.

Rules written against library defaults therefore catch well-behaved clients along with everything else, and there is no way to be exempted.

A useful string has three parts

A name identifying the software, a version, and a contact address covers everything a server operator needs to make a reasonable decision about the traffic.

The version matters when behaviour changes between releases, since it lets an operator report a problem against a specific version rather than the software generally.

The contact address is the part most often omitted and most often needed, because without it the only available action is blocking.

Keeping the library token is good practice

Appending an identity rather than replacing the default keeps the library information available, which helps when diagnosing protocol-level behaviour.

This matches how browsers construct their strings and stays within the format's grammar of multiple product tokens.

It also means a server can recognise the underlying library's known quirks while still attributing the traffic to the right software.

Imitating a browser causes problems

Setting a browser string on an automated client is common and counterproductive. It removes the operator's ability to treat the traffic appropriately.

Traffic that claims to be a browser is measured against browser expectations, and automated request patterns look anomalous against those expectations.

Honest identification is treated better in practice, because operators generally accommodate automation that identifies itself and explains what it is doing.

Distributed software needs configurable identity

Software installed by many operators should let each add their own contact information, since the author cannot be the contact for every deployment.

A default naming the software with a link to its documentation, plus an option to append an operator string, covers both cases.

Server operators seeing unfamiliar traffic can then identify the software and reach whoever is actually running it, which is the outcome the convention exists to produce.