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)
Hey guys! Yeah let's hold off on native comments for now. It should be easy enough to add later if we want, but let's keep it as simple as possible for now.
I added an example for the churches API let me know if it needs any tweaks. @mwic, I tried to make all the changes that we discussed yesterday, but take a look and let me know if I missed anything.
@jlandon, I was thinking for the initial version we will just hardcode Watermark's
CHURCH_ID
into the app. Let me know if you see any gripes big or small with the current API docs. We want to get it as close to right the first time as possible.Thanks guys!