HTTP API

[bbatsov]

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]

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?

• https://clojuredocs-edn.netlify.com/clojure.core/map.edn
  • EDN file for everything about clojure.core/map.
• https://clojuredocs-edn.netlify.com/clojure.core/map/see-alsos..edn
  • EDN file containing only :see-alsos of clojure.core/map

👍 Pros.

• We don't need to maintain the server providing the API (Netilify do the work for us)
• Easy to do

👎 Cons.

• We need to have a more detailed (and partially duplicated) file to serve detailed requests
• We can't provide functionalities like keyword searches, of course.

[bbatsov]

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]

OK, I'll fix codes to generate them 😄

[liquidz]

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

• https://clojuredocs.org/clojure.data/Diff
• https://clojuredocs.org/clojure.data/diff

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.

• https://clojuredocs-edn.netlify.com/clojure.data/_Diff.edn
• https://clojuredocs-edn.netlify.com/clojure.data/diff.edn

@bbatsov Do you have any ideas?

[bbatsov]

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]

Yeah, there are only 5 cases as follows.

• clojure.core.async/pub
  • https://clojuredocs.org/clojure.core.async/Pub
  • https://clojuredocs.org/clojure.core.async/pub
• clojure.core.async/mult
  • https://clojuredocs.org/clojure.core.async/Mult
  • https://clojuredocs.org/clojure.core.async/mult
• clojure.core.async/Mix
  • https://clojuredocs.org/clojure.core.async/Mix
  • https://clojuredocs.org/clojure.core.async/mix
• clojure.data/Diff
  • https://clojuredocs.org/clojure.data/Diff
  • https://clojuredocs.org/clojure.data/diff
• clojure.spec.alpha/spec
  • https://clojuredocs.org/clojure.spec.alpha/Spec
  • https://clojuredocs.org/clojure.spec.alpha/spec