hoogle
hoogle copied to clipboard
ndmitchell
Specification for JSON API
It would be nice if we can provide a specification for Hoogle's JSON API (presumably using servant)
How would servant help? The current code is pretty simple, and I wouldn't like to complicate it with type-level routing unless it gives concrete benefits.
A document describing the JSON API would be great, with examples and such. I'd welcome such a contribution, but am unlikely to do it myself, as I don't actually use the JSON API.
The benefits of Servant would largely be in generating documentation that doesn't need to be actively maintained separately, as well as generating things like swagger specifications (which can be used to generate API clients in a number of languages and to host interactive API documentation (see the right pane)) and elm and purescript bindings.
Personally I think the benefits are fairly convincing, but I also tend to use Servant on all of my projects already, so :)
My only holdback would be that it's a bit overengineered for Hoogle's usecase, but I'm sure anyone developing anything against Hoogle would appreciate both the interactive documentation and getting API bindings effectively for free.
Writing the docs should take under an hour. I don't think the docs would have changed since they were written. Auto-generating bindings might be useful, but equally, the Hoogle JSON API wasn't designed for massive use, so I'm not totally against a little bit of friction there.