REST structure where 'discoverability' is not possible

Question

I have trouble figuring out any option on how to best define a REST/HATEOAS service where exhaustively listing available resource options is not a possibility due to the huge number of them.

In particular, a part of the system would be resources for indexed word usage statistics in a large corpus of text - something like GET http://mysite.org/word_statistics/foobar that returns information on foobar and URI's to documents where foobar is used.

However, I can't provide any reasonable way where the app might discover the actual http://mysite.org/word_statistics/foobar link - the canonical approach seems to be to provide a resource like http://mysite.org/word_statistics that would return a list of the individual URI's, but in my case that list would be around a gigabyte, so not reasonably practical. So I'd need to give the requesting app something like http://mysite.org/word_statistics/{your_query_here}, but there seems to be no RESTful way to do that.

How should this be done properly?

Answer 1

I would just follow the classic search pattern used in many places.

• http://example.org/word_statistics -- this would return everything, words and links, but you don't want to return everything, so you don't and instead return the appropriate error code with perhaps descriptions of what query options you do support. Or you could return everything, but in pages (10, 100, 1000 words at a time...).

• http://example.org/word_statistics/{word} -- the statistics for the given word.

• http://example.org/word_statistics?like=word -- this returns a list of words that are "like" word, this could handle misspelling and soundalikes, or whatever.

• http://example.org/word_statistics?from_word=word1&to_word=word2 -- returns a list of words that starts, alphabetically, with from_word and goes to to_word, but under the same limit and paging constraints you'd have for the original list.

You could also do something like:

• http://example.org/{document}/words -- that returns the words that are just in that document, with links to their statistics.

All sorts of things you can do here. But, the gist is that a basic search pattern should fill the need readily.