A RESTful way to verify server state [closed]

Question

I'm interested in building verifications into a REST service to help with service monitoring.

For example, one could run assertions like http://example.com/posts/verify?min-posts=5&since=1-hour-ago which would respond with an error unless 5 new posts had been created in the past hour.

Are there any existing services like this, or best practices? I'm particularly interested in a recommended error code for failed verifications, as I can't really see anything appropriate in the 4xx series. Errors like "Precondition Required" and "Internal Server Error" are more about the actual request or processing of it, than the meaning of it.

Answer 1

Supposing you were to ask for the same verification twice in a row. Would you get the same answer? Would it significantly affect the state of the resources? If you are logically going to get the same answer (which doesn't need to be byte-identical, but rather just “the same” in some higher-level sense) and won't be affecting the state of the resources in any meaningful way then a GET makes a huge amount of sense. That in turn means that any parameters you pass will either be encoded in the path or as query parameters. All of which seems very reasonable to me.

What would the response be? Well, I'd be tempted to say at least consider making it always be 200 and have the response document describe what passed or failed: on one level at least, you're successfully retrieving a document that describes what happened, even if that is a description of a failure.

You could also model a failure as one of the 500-series errors (save the 400-series for “you gave a bad request” problems, such as passing nonsense query parameters) as the problem would be with the state of the service, not the client. But frankly I wouldn't really recommend it; a failure to validate isn't the service's fault as such, but rather just some unfortunate data that the service has been entrusted to look after. (On an operational level, the validation routine itself succeeded, but the data was invalid. It's like a the famous surgeon's dictum: the operation was a success, but the patient died.)

Under no circumstance would I return a 204 No Content from a validation. It's always better to send a message back saying at least a summary of what was checked; the client can throw it away if it wants, but in principle it should be able to show the information to the user.

---

When working out what response to use, remember that any RESTful web service should be usable by an ordinary web browser with Javascript disabled (though with capabilities that most real browsers don't normally enable, to be fair) at least in principle. Any error responses should therefore be ones that are used for that sort of purpose in a normal web interaction, and this greatly restricts what you can do with the 400-series errors, as most have very stylised client recovery actions.

Answer 2

I don't exactly understand your specific example, but I'll still try to give my advice.

REST is all about entities, or state, and state transitions. It kinda seems like what you want to do is query for some state. Let's look at the common HTTP verbs:

POST - Commonly used for creating additional state on the server.

PUT - Commonly used for creating or updating existing state on the server.

DELETE - Used for deleting some state from the server.

The above methods don't make sense for checking existing state, which you want to do. I've left out CONNECT, TRACE, and OPTIONS, since those also don't seem to be appropriate here.

GET - Used for getting state from the server.

HEAD - Same as GET but only returns the metadata.

So it seems like GET or HEAD may be most appropriate, depending on where you are returning the information (in the metadata or entity/body). Since you are not transferring state to the server, but querying it, perhaps it should be the responsibility of the client making the assertion to do that instead of the server doing assertions.

If you want to take advantage of HTTP error codes, perhaps you could add a query parameter. For example HEAD posts?min_posts=5 could return 404 (Not Found) if there are no posts meeting that requirement. Otherwise it could return 204 (No Content) if it met the requirement.

If you don't want to use GET or HEAD, you could try using POST, but that requires you to create some entity representing the state that you are POSTing, ex. an "assertion" entity. It could return 409 (Conflict) if the assertion fails, since the state of the resource in the request (i.e. the assertion) has a conflict (i.e. is not true or did not pass). If the assertion passes, you could return 204 (No Content). This approach kinda seems like a hack to me, though. But it may actually make sense, depending on the details of your system.

I also want to add that a "REST" API is rarely implemented correctly. Sometimes due to acceptable/practical tradeoffs from the REST guidelines. Other times due to ignorance of what REST means.

Answer 3

I am not aware about a best practice for this.

What I would do, is to send the assertions as custom request header with the normal request.

X-ASSERTION min_posts=5.

Then on the server first to parse the header and process the assertions and depending on the result either return HTTP error (as proposed in other answer 204 No Content, 409 Conflict or other more appropriate), or the result of the request.

Additional information about the result of the assertion could be returned again as custom header in the response headers.

STATUS 409 Confilct; X-ASSERTION-RESULT min_posts=3

I think this would be in compliance with the REST principles, as the assertion is actually exchanging metadata (data about the data) and the place for the metadata is in the header.

However in practice this could be unreliable or difficult to implement as many firewalls or shared hosting servers would strip out the custom headers.