We're sorry Aspose doesn't work properply without JavaScript enabled.

Free Support Forum - aspose.com

SUGGESTION: RESTful Web API's MUST return status codes consistent with HTTP standards

Hello Aspose,

I’m in the process of working exception-handling into the various points in code that call out to your services, and I’m troubled by what I’m finding in terms of responses.

RESTful Web API’s must return HTTP status codes for all types of responses. After POST-ing an executeTemplate, a successful result will include a links to resources for converting the result to various formats (which is good and moves your service towards HATEOAS-compliance). However, if the client then requests one of these resources and the file is no longer there (for whatever reason–in this case I deliberately deleted the merge file for testing purposes), your service does not return a status code. It returns a non-standard message instead. The proper code to return in this case would be 404.

In fact, for each Web API endpoint, your documentation needs to indicate all of the possible response status codes for that endpoint, even 500 if, indeed, an internal error is encountered. So, for example, in the case above, if your service is not able to convert the merge document to, say, a PDF, then a status code of 500, 503, or perhaps even a 204, should be returned. It could even be a 415 if a media format has been requested that is not supported.

It would seem that the approach your taking is largely 200-centric: A response code comes back if everything went well, but otherwise a non-standard message is returned. This is not uncommon in first-generation RESTful Web API’s. But it’s not RESTful, and it really wreaks havoc on exception-handling.

This, coupled with the fact that the endpoints themselves are not RESTful, is a little problematic. I would recommend that, for v1.2 or v2.0 of your API, you move to RESTful endpoints and RESTful responses.

Just as an example, we’re using this endpoint: /words/{name}/executeTemplate. This is actually an action-based, SOAP-style endpoint, not REST. Converting this to a RESTful format, we would have /words/templates/{name}, which, together with the HTTP verb POST, would give rise to the notion of “executing” a template. The distinction between pulling the file from storage or simply processing an attached file (no storage) would be taken up in the body of the POST. Also, the distinction between merge fields and mustache tags could be taken up in parameters (e.g. ?tags=classic, ?tags=modern, ?tags=mixed, etc.).

Ideally, your URLs should be noun-based, letting the HTTP verb signify the action.

Anyways, these are just suggestions. You guys have created an awesome service!

Thank you.

Hi Eric,

Thanks for your suggestions; all of them are valid. The issues have been raised with the concerned teams. These will be discussed internally and you will be updated as soon as we take a decision on it.

Best Regards,