This document describes the functionality of a Join The Journey API that will be used by a mobile app and potentially other software to ingest the app's data. As it makes sense, this API will use the REST conventions.
All endpoints will be prefixed with "/api".
Endpoints:
Returns a list of active Church
objects available through this API.
Shows the data for the specified date. The id of the resource is the
date in ISO 8601 format. The days resource is a subresource of churches
since multiple devotionals can exist for a given day (e.g.
/api/churches/1/days/2014-05-02). First lookup a valid CHURCH_ID
from
the Churches Index endpoint.
The first version of the API will only return data in the JSON format with UTF-8 character encoding.
To facilitate future versions of the API. Applications should specify the desired version of the API in the "Accept" HTTP header. If no version is specified the latest will be used with the default data format.
The structure of the Accept header should be the following:
application/vnd.jointhejourney[.version][+json]
The items in square brackets are optional. The first version of the API will be "v1". So to make a JSON formatted version 1 request to the API the Accept header would look like this:
Accept:application/vnd.jointhejourney.v1+json
For the first version nothing will be done server side to accommodate this as there will only be one version, but this will lock your client into that version should the API format be changed in the future.
This section defines the data objects that will be served by the API.
- id (unique id for this
Church
) - name
- subdomain
- id (unique id for this
Day
) - date (In ISO 8601 format)
- passage (Structured as a
Scripture
object) - title
- bio (HTML formatted)
- author (Structured as an
Author
object) - key_verse (HTML formatted)
- central_truth (HTML formatted)
- reflections (HTML formatted)
- discussion_questions (HTML formatted)
- memory_verses (HTML formatted)
- web_url (link to web for this day)
- previous_day (Previous devotional day's date in ISO 8601 or null)
- next_day (Next devotional day's date in ISO 8601 or null)
- first_name
- last_name
- image_url
- image_width
- image_height
- reference
- text (HTML formatted)
- translation (name or abbreviation)
- copyright (HTML formatted)
- link (URL to more info about the translation)
This looks great for v1, Travis! One comment I have is about the long text blocks for a devotional (i.e. central_truth, reflections, and discussion_questions). I've seen that some of the authors use "em" and/or "strong" text for certain words, so are you thinking the API would just send that text as raw HTML to preserve the format?