What are the best practices for the root page of a REST API?

Question

I would like to know if there is some best practices about the root endpoint for a REST web service? I mean, should it be a short documentation about the usage of the API itself? Should it be an XML document describing all methods available? Should it only return "unknown method"?

Answer 1

The question is perfectly clear to me.

I think it should respond with 404. If there is no resource associated with the root path, then there is nothing to return.

If you feel that 404 is not helpful, then it would also be OK to return the URL of the documentation.

Answer 2

REST is supposed to be self describing so having the root show an error is poor design in my opinion. I like the root to contain information that allows you to navigate the rest of the API. So for example the root might contain a link to a list of product categories from which the API user can select a category and then a list of products etc. A self describing API means less documentation to write and keep updated!!