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)
Yep, that makes a lot of sense just to query the ESV API once on the backend and then include the raw HTML from that query in the JSON response. Makes the client API calls nice and simple. :)
Not sure if this should be in v1 or not, but what are your thoughts on including the ability to read and post comments from the client? We could just append an array of
Comment
objects to theDay
objectComment
objectUser
object)User
objectAnd then posting a new comment could just be:
POST /api/days/YYYY-MM-DD/comment
- Add comment for dayThe web app for JTJ has comment support, but I'm not sure how important that would be for the native app. Maybe this could be a v1+ feature.