3 ms·
https://freebibleapi.com/api/translation https://freebibleapi.com/api/translation: {"error":"Error loading translations"} … hmm. Well, reloaded it and it wo
by chrismorgan 5y ago
https://freebibleapi.com/api/translation https://freebibleapi.com/api/translation:
{"error":"Error loading translations"}
… hmm. Well, reloaded it and it worked second time, showing that it’s got two translations: KJV and ASV, both public domain.
(I observed similar errors in other URLs from time to time.)
The key thing to this API seems to be its structure, that it’s relational like SQL but without joins, exposing the foreign keys and you have to look things up that way. This isn’t a model that makes much sense to me, so I’m curious if you’ve got any explanation of why or where this model might make sense.
As an example, if you wanted to look up Exodus 3:4 in the ASV:
• https://freebibleapi.com/api/translation https://freebibleapi.com/api/translation, then (using jq syntax) `select(.name == "English ASB") | .id` (that’s a very weird name for the ASV, incidentally), yields 35.
• https://freebibleapi.com/api/translation/35/book https://freebibleapi.com/api/translation/35/book, `select(.name == "Exodus") | .id`, yields 15.
• https://freebibleapi.com/api/translation/35/book/15/chapter https://freebibleapi.com/api/translation/35/book/15/chapter, `select(.chapter_number == 3) | .id`, yields 525.
• https://freebibleapi.com/api/translation/35/book/15/chapter/525/verse https://freebibleapi.com/api/translation/35/book/15/chapter/..., `select(.verse_number == 4) | .content`. Plain text, incidentally; no footnotes or anything being kept here.
It needs four sequential requests. If you want to avoid that, you need to cache the list of translations, book IDs, chapter IDs, verse IDs… and as soon as you’re doing any of that, I question why you’d use such an API rather than just storing the full text of the translation/s yourself, as a JSON blob for example if you’re keeping things simple.
IDs for access rather than semantic identifiers seems very strange, since there are meaningful identifiers that won’t be changing: you can give a short string for translations (ASV, KJV), some form of book name for the books (I’d suggest OSIS book abbreviations <https://wiki.crosswire.org/OSIS_Book_Abbreviations https://wiki.crosswire.org/OSIS_Book_Abbreviations>), and chapter and verse numbers. Autogenerated IDs are just unnecessary obstruction.
I’d also merge each pair of URLs, e.g. /translation/35 gives the translation object, and /translation/35/book gives the array of its children: I’d merge them to just one route, yielding {...translation, "books": [...books]}. Same for book and chapter. (Verse would be unchanged as it doesn’t have any children.)
Taking it all together, accessing just Exodus 3:4 in the ASV would go from being /api/translation/35/book/15/chapter/525/verse/15835 to being /api/ASV/Exod/3/4.
Your current /api/book, /api/chapter and /api/verse routes don’t fit into this picture; I’m again curious if you think they’re actually useful—they feel more like things that just happened because of how an API generator worked.
- spc476 5y agoYour method sounds similar to the system I used for <http://literature.conman.org/bible/ http://literature.conman.org/bible/>. I also correct for spelling mistakes. Right now it only returns HTML, and only has the King James version of the Bible, but it was an example I wrote over 20 years ago to see about addressing Bible verses on the web.
- chrismorgan 5y agoFor specifying references in a machine-friendly way, I reckon OSIS’s references are probably the best idea, minus the ability to refer to portions smaller than a verse (which is two features: sub-identifiers and fine-grained references). See osisRef in <https://ebible.org/osis/OSIS2_1UserManual_06March2006_-_with_O'Donnell_edits.PDF#page=90 https://ebible.org/osis/OSIS2_1UserManual_06March2006_-_with...>. My main complaint about osisRef is that it only allows contiguous ranges. Anyway, OSIS references will yield results like Rev.13.18, Exod.20.3-Exod.20.17, Gen.6.9-Gen.9.17. Rigid formats are so much easier to work with. Once you’re allowing any flexibility, you get into all kinds of hot water of disappointed expectations. Will you support “2K”, “2 Ki”, “IIKgs”, “II Kng”, “2 Kings”, &c. as all referring to what OSIS calls 2Kgs? Support at least “:”, “.”, “v”, “vv” as a chapter/verse divider? If I ask you for “2 Mose 3:4”, will you resolve that to Exod.3.4? (German has 1–5 Mose instead of Genesis–Deuteronomy.) It’s all kinds of fun; most tooling does a fairly poor job of it in my experience. libsword, by far the most popular foundation for open-source Bible software, does quite poorly in certain cases that keep on annoying me. (Perhaps I should submit patches like adding 1K and 2K as abbreviations and tweaking its reference parser which is a bit of a monstrosity, but I’m just choosing to start from scratch for my own software focused on Bible reading which I’m working on, a domain that no one has made any serious attempt on, as I judge it.)
- spc476 5y agoNo one has asked before. Also, I only have an English version (the King James in particular). I don't see much of an issue with adding alternative book names (I also support two letter abbreviations) other than working on a twenty-plus year old Apache module. I originally planned on supporting non-contiguous ranges, but gabe up on that to get something out.