BibleGet I/O service endpoints

There are 3 API endpoints for the BibleGet I/O project, reachable at the URL https://query.bibleget.io. The first official release on GitHub was v2.4. Since then, the v2 endpoints (currently at v2.9) have also become reachable at the URL https://query.bibleget.io/v2/.

Starting with the v3 release, the v2 endpoints will ONLY be available at https://query.bibleget.io/v2/, the v3 endpoints will ONLY be available at https://query.bibleget.io/v3/, and NO endpoints will be available at https://query.bibleget.io . This way it will be become clear which version of the endpoint is being used. Any significant changes that would break functionality in a plugin or application will only be applied between major versions, in order to allow plugins or applications to handle the versioning and avoid breaking functionality.

Along with the information provided below, Swaggerhub documentation can be found here (kudos to @MichaelRShelton for generating the docs from the Swagger docker image).

Code quality and Endpoint validity | Main branch | Development branch | OpenAPI validation | | :---------: | :----------------: | :----------------: | | | | |

Architecture (v3)

The v3 codebase is built on PHP-FIG PSR standards and follows a modern, standards-compliant architecture:

| Standard | Implementation | Purpose | |----------|---------------|---------| | PSR-4 | Composer autoloading (BibleGet\Api\ → src/) | Class autoloading | | PSR-7 | nyholm/psr7 | HTTP message interfaces | | PSR-15 | Custom handlers and middleware | Request handlers and middleware | | PSR-17 | nyholm/psr7 (Psr17Factory) | HTTP factory interfaces | | PSR-3 | monolog/monolog | Logging | | RFC 9457 | Custom exception hierarchy | application/problem+json error responses |

All requests are routed through a single front controller (public/index.php) via a PSR-15 middleware pipeline:

1. ErrorHandlingMiddleware — catches all exceptions and returns RFC 9457 application/problem+json responses
2. LoggingMiddleware — logs request/response details via Monolog
3. Handler — the endpoint-specific PSR-15 request handler

Response emission is handled by laminas/laminas-httphandlerrunner (SapiEmitter).

v3 Routes

| Route | Handler | Description | |-------|---------|-------------| | /v3/quote | QuoteHandler | Bible quote retrieval | | /v3/metadata/biblebooks | MetadataHandler | Book names in 25+ languages | | /v3/metadata/bibleversions | MetadataHandler | Available Bible versions | | /v3/metadata/versionindex | MetadataHandler | Chapter/verse indexes | | /v3/search | SearchHandler | Keyword search |

Testing & CI

• PHPUnit 11 with Unit, Integration (MySQL), and Server (HTTP) test suites
• PHPStan level 10 static analysis
• GitHub Actions CI runs all test suites and static analysis on pull requests

/v3/quote

This is the main API endpoint for all queries for biblical texts and quotes, reachable at the URL https://query.bibleget.io/v3/quote.

Both GET and POST requests are supported. The endpoint is CORS enabled, which means that ajax requests can be made directly against the endpoint without getting cross-domain restriction errors. HSTS is enforced on the whole BibleGet server, both for the website and the API endpoints, so only the https protocol can be used for requests. Since the certificate used on the server is a Let's Encrypt issued certificate, it should be recognized by most platforms, this is not however the case for many Java runtimes in which the keystore often does not have a copy of the Let's Encrypt CA or Intermediate certificate (see here). In these cases, it may be necessary for the application to ensure that a copy of the Let's Encrypt CA or Intermediate certificate is installed to the keystore in order for valid requests to be made to the BibleGet API endpoint.

For the time being, authorization is not required to access the endpoint. However anyone who intends on using the endpoint is requested to use the appid parameter explained below in order to identify the source of the requests to the endpoint. And especially for web-based tools (apps, plugins), it is very important to use some kind of cache mechanism, in order to avoid unnecessary repeated requests to the API endpoint. Restrictions on the maximum amount of requests permitted daily from any given IP address or web host are enforced.

Think of this scenario: you create a web page that makes an AJAX request for a Bible quote and displays the result. But anyone on the internet can reach this web page. And in just one day, 300 people happen to open that web page for one reason or another. Every time the web page is opened, whether by actual people or by internet crawlers, the page makes an AJAX request to the BibleGet API endpoint just to display the same exact Bible verse every time. So in one day, 300 requests were made to the API endpoint from the same page for the same Bible verse. This is an irresponsible usage of the endpoint. If the web page used a form of local storage, it could store the data retrieved from the API endpoint in local storage. This way when anyone (whether an actual person or a web crawler) accesses the page, the Bible quote will be retrieved from local storage first, and if it not present in local storage it will be retrieved from the API endpoint and saved to local storage. This is not as necessary for desktop applications, where it is usually just one person using the desktop application, it would be very rare for anyone to make 100 requests in one day for the same Bible verse in a desktop application. However this danger does very well exist for web pages.

Types of data that can be returned from the API endpoint are JSON, XML, and HTML.

PARAMETERS

• query: (required) should contain the reference for the Bible quote. There is no default value, this parameter must be provided. The reference must use standard notation, whether English notation or International notation (e.g. John3:16 or Giovanni3,16), see the page Standard notation for biblical quotations for more information. The endpoint does check for the validity and correctness of the Bible reference, and will return error messages for badly formed references, however the application forming the request should also do validity checking in order to prevent bad requests from even reaching the server. This will help keep unnecessary load off of the server. The source code of the endpoint can be inspected for the REGEX checks that are used to check the validity of the Bible references, as can the source code of the official apps for WordPress, for Google Docs, for Microsoft Word, for Open Office and for LibreOffice.
• version: (optional) the version of the Bible to retrieve the quote from, default value CEI2008 (the Italian version of the Catholic Episcopal Conference). With this parameter you can specify the biblical version you want to retrieve the quote from. You can also specify several versions as a comma separated list, for example to compare multiple versions of the biblical texts. The possible values should be retrieved via the /v3/metadata API endpoint.
• return: (optional) the format in which the structured data should be returned, default value json. This parameter takes one of three values: json, xml, or html. Rather than using this parameter, it is recommended to set the Accept header to the desired type for the response data. The Accept header can be set to application/json, application/xml, or text/html.
• appid: (required) identifies the application generating the request. For the time being, there is no kind of registration required for authorization with api keys and secrets. Requests can be made freely to the endpoint, which for now is completely open. However responsible usage of the endpoint is required, such as filtering for valid Bible references and using cache to avoid multiple requests for the same Bible reference. In order to help understand and monitor the usage of the endpoint by various applications, the appid parameter is required to know where the request is coming from. This will also be useful for the statistics of the requests made to the service endpoint. Using this parameter can be considered the basic registering mechanism for applications that make use of the service endpoint.
• pluginversion: (optional) lets the engine know which version of a plugin is being used to generate the request (the plugin being indicated in the appid parameter). See