Standard API Utility Endpoints

Many - possibly most - APIs that we work with make one or two utility endpoints available for checking connection, authentication, server time, etc.

For example "ServerTime" and "ConnectionStatus" (or even, simply, "Connected"). The first call simply returns a server time-stamp which can act as both a time reference and a connection check. Better is the second which can return full connection details such as authentication status, latency, etc but can be as simple as true/false. (This is actually better named "Authenticated" or "Authorized" as if the connection itself isn't made, there won't be any response.)

The reason we have a need for at least one of these is to handle the case where authorization details become corrupted or are lost and re-authorization is needed. Without this, actual production calls failing are the only indication that something is wrong. It's better if an innocuous connection test can be made external to production processes.

  • Steven Cinquegrana
  • Aug 5 2018
  • Attach files
  • Steven Cinquegrana commented
    April 10, 2019 21:06

    One more thing that could be added are error responses; the ability to generate errors for testing error handling is a pretty common, even standard feature of well-designed APIs. For example, our code should be able to make requests to an endpoint such as Utility/get_error_gen(500) to receive back a 500 Internal Server Error error on a GET request, Utility/post_error_gen(500) to receive back a 500 Internal Server Error error on a POST request, etc.

  • Mike Greineder commented
    August 29, 2018 15:01

    Would be nice to also add a "CurrentDailyCallCount" so we can monitor when we approach our limit.