Good practice: Set a user-agent for API requests

🛠️ Good Practices
1

Currently, we don’t enforce standards for including user-agent headers with API requests.
However, we appreciate if you send them, as it helps with analyzing traffic patterns on our end and to proactively reach out to you when we see room for improvement.

When setting the user-agent, please set up as follows:

  • Include your company, the app that is making the request and its version, separated by slashes: <company>/<app>/<app version>, e.g. user-agent: gridx/xenon/1.8.2
  • Keep the charset simple, don’t try to be fancy
    • Use only 0-9, a-z, /, -, _, .
    • Already excluded, but just to make sure. Don’t use emoji and UTF-8 in the header. We can deal with it, but we’ve seen other systems struggle and it makes reports look weird.
  • Include the full version number, don’t restrict it to the major version. That will help with analyzing changes in behavior between versions.

Example

curl --request GET \
   --url 'https://api.gridx.de/systems?page=1&per_page=5' \
   --header 'accept: application/vnd.gridx.v2+json' \
   --header "authorization: Bearer $GRIDX_TOKEN" \
   --header "user-agent: gridx/dev-community/v1.0.0"