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)
@jlandon that's a great point. I'll modify the gist this afternoon to include the raw HTML. On including scripture in the API it looks like ESV allows you to syndicate in an RSS feed. It doesn't explicitly say anything about an API so I think we might be ok to include it. I'll make sure on that before we move forward, but I think that might be the right way to go. It allows us to keep the client app simple and not have to know how to talk to different API endpoints and it reduces the number of separate calls that have to be made. Any thoughts on that?