search

clojure-emacs / clojuredocs-export-edn

Daily EDN exports of ClojureDocs's database.
Eclipse Public License 2.0
9 stars 3 forks source link

HTTP API #2

Open bbatsov opened 4 years ago

bbatsov commented 4 years ago

I've been thinking lately that it'd be great if we exposed a simple HTTP API to query directly our ClojureDocs EDN export. This would simplify the lives of clients a lot, as they won't have to deal with keeping a local copy of the data and will be able to fetch some data even without Orchard or cider-nrepl.

I guess the simplest API would be - clients request the docs for a symbol and get everything we have about it. A more polished API would allow for clients to specify they want only part of the data for some symbol (e.g. :see-alsos). @liquidz What do you think?

liquidz commented 4 years ago

I also think it's great. But I'm also feeling it's too much to provide API because the API is not so dynamic. 🤔

For example, how about splitting the EDN file beforehand as follows?

👍 Pros.

👎 Cons.

bbatsov commented 4 years ago

But I'm also feeling it's too much to provide API because the API is not so dynamic.

Great point!

https://clojuredocs-edn.netlify.com/clojure.core/map.edn

I like this idea, as for most clients it'd be quite convenient to work with that. I don't think we need to a smaller granularity than this (e.g. breakdown for see alsos, notes, etc), as the EDN file for each symbol shouldn't be very big and clients can fetch it process it locally additionally.

liquidz commented 4 years ago

OK, I'll fix codes to generate them 😄

liquidz commented 4 years ago

I have one point to discuss. There are some vars which has same name like follows.

Some filesystems are case insensible, so it couldn't write EDN files separately. So I'm considering to add a prefix such _ for vars which starts with upper case.

@bbatsov Do you have any ideas?

bbatsov commented 4 years ago

I'll have to think about this. Another approach would be to have a different convention for data types, as those are the things with capitalized names. How many such cases are there in total? I assume not many, right?

liquidz commented 4 years ago

Yeah, there are only 5 cases as follows.