2

What endpoints should I provide, if any, to permit connectivity / availability testing for my web services / Web API?

TL;DR

I am developing both the server and client in an enterprise environment. The client will interface with the server via an RESTful Web API. I would like to provide an indication to the user that they have correctly entered the Web API's root URL correctly. I would also like to implement connectivity monitoring of the API in the future.

None of the public APIs (Facebook, Twitter etc) that of have looked have a dedicated end point for connectivity testing. There are a number of web sites that provide availability monitoring of public APIs. One of them, Watchmouse, reported they preform their availability testing by actually exercising the API (logging in, perform an action, and testing the results).

On the other hand calling the root URL for CouchDB returns and configurable message and the CouchDB version.

Should I provide dedicated endpoints for connectivity / availability testing? If so what endpoints? Or should I just exercise existing endpoints?

Improve this question

2 Answers 2

Reset to default
4

I include a method like this in all of my web services

string GetVersion()

Which just returns the version of the running assembly on the server. It provides an easy way to ping the service to ensure it is running. As a side effect, it actually gives you some useful information about the server.

It's obviously not as good as actually exercising the API, but its easy enough to add to any existing service.

Personally, I don't think there's any need to define anything more than that. If you want to test the functionality service, then you will need to use the actual service methods.

Improve this answer
1
  • Right, allow a simple call. And GetVersion() is then a good candidate, because this falls under 'preparing for future extensions/modifications'. I have learned never to release anything without version numbers. Commented Mar 20, 2013 at 7:29
0

If the root returns a well-defined document that is unique to your server, then any client can tell that it was entered correctly. Why do you wish something more?

In addition to p.s.w.g's suggestion of a 'GetVersion()', you can also do a HEAD request and see if the server responds. Would an expected value for the "Server:" response header suffice?

You want to 'implement connectivity monitoring of the API in the future.' Will you support multiple versions? That is, the problem with a GetVersion() API is that you have to change clients and servers at the same time. Otherwise, a v2 client will refused to connect to a v3 server, even if the v3 service is backwards compatible so that v2 and v3 clients can connect to it.

One way to handle this is to have the root return a document containing a list of service points, where the points are versions. Personally, that's what I do. For example, it may point to services handled on other machines.

Another is to include a version value in the request and let the server figure out what to do. A third is to just go ahead and try new API entry points, and if there's a failure then the server isn't new enough.

Perhaps more useful than something which returns the server version is a summary diagnostic page, which shows that the server is up, that it's able to connect to the database (if you have one), etc. But the determination of what it does depends on your situation.

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.