Journey API Definition

README.md

Journey API Proposed Spec

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.

Endpoints

All endpoints will be prefixed with "/api".

Endpoints:

GET /api/churches - Churches Index

Returns a list of active Church objects available through this API.

GET /api/churches/CHURCH_ID/days/YYYY-MM-DD - Days Show

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.

Data Formats

The first version of the API will only return data in the JSON format with UTF-8 character encoding.

Versioning

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.

Object definition

This section defines the data objects that will be served by the API.

Church object

• id (unique id for this Church)
• name
• subdomain

Day object

• 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)

Author object

• first_name
• last_name
• image_url
• image_width
• image_height

Scripture object

• reference
• text (HTML formatted)
• translation (name or abbreviation)
• copyright (HTML formatted)
• link (URL to more info about the translation)

churches_example.json

[
  {
    "id": 1,
    "name": "Watermark Community Church",
    "subdomain": "wmcc"
  },
  {
    "id": 2,
    "name": "Hill Country Bible Church Austin",
    "subdomain": "hcbc"
  }
]

days_example.json

/* Example response from /api/days/2014-05-02 */
{
  "id": 88095,
  "date": "2014-05-02",
  "passage": {
    "reference": "Ephesians 2:11-22",
    "passage": "<div class=\"esv-text\"><h3 id=\"p49002011.01-1\">One in Christ</h3><p id=\"p49002011.04-1\"><span class=\"verse-num\" id=\"v49002011-1\">11&nbsp;</span>Therefore remember that at one time you Gentiles in the flesh, called “the uncircumcision” by what is called the circumcision, which is made in the flesh by hands— <span class=\"verse-num\" id=\"v49002012-1\">12&nbsp;</span>remember that you were at that time separated from Christ, alienated from the commonwealth of Israel and strangers to the covenants of promise, having no hope and without God in the world. <span class=\"verse-num\" id=\"v49002013-1\">13&nbsp;</span>But now in Christ Jesus you who once were far off have been brought near by the blood of Christ. <span class=\"verse-num\" id=\"v49002014-1\">14&nbsp;</span>For he himself is our peace, who has made us both one and has broken down in his flesh the dividing wall of hostility <span class=\"verse-num\" id=\"v49002015-1\">15&nbsp;</span>by abolishing the law of commandments expressed in ordinances, that he might create in himself one new man in place of the two, so making peace, <span class=\"verse-num\" id=\"v49002016-1\">16&nbsp;</span>and might reconcile us both to God in one body through the cross, thereby killing the hostility. <span class=\"verse-num\" id=\"v49002017-1\">17&nbsp;</span>And he came and preached peace to you who were far off and peace to those who were near. <span class=\"verse-num\" id=\"v49002018-1\">18&nbsp;</span>For through him we both have access in one Spirit to the Father. <span class=\"verse-num\" id=\"v49002019-1\">19&nbsp;</span>So then you are no longer strangers and aliens,<span class=\"footnote\">&nbsp;<a href=\"#f1\" id=\"b1\" title=\"Or 'sojourners'\">[1]</a></span> but you are fellow citizens with the saints and members of the household of God, <span class=\"verse-num\" id=\"v49002020-1\">20&nbsp;</span>built on the foundation of the apostles and prophets, Christ Jesus himself being the cornerstone, <span class=\"verse-num\" id=\"v49002021-1\">21&nbsp;</span>in whom the whole structure, being joined together, grows into a holy temple in the Lord. <span class=\"verse-num\" id=\"v49002022-1\">22&nbsp;</span>In him you also are being built together into a dwelling place for God by<span class=\"footnote\">&nbsp;<a href=\"#f2\" id=\"b2\" title=\"Or 'in'\">[2]</a></span> the Spirit.  (<a href=\"http://www.esv.org\" class=\"copyright\">ESV</a>)</p></div>",
    "translation": "ESV",
    "copyright": "All Scripture quotations, unless otherwise indicated, are taken from The Holy Bible, English Standard Version. Copyright &copy;2001 by <a href=\"http://www.crosswaybibles.org\">Crossway Bibles</a>, a publishing ministry of Good News Publishers. Used by permission. All rights reserved. Text provided by the <a href=\"http://www.gnpcb.org/esv/share/services/\">Crossway Bibles Web Service</a>.",
    "link": "http://www.esv.org"
  },
  "title": "OUTSIDERS WELCOME",
  "author": {
    "first_name": "Caryn",
    "last_name": "Blocker",
    "image_url": "//www.jointhejourney.com/img/writers/8378.jpg",
    "image_width": 179,
    "image_height": 237
  },
  "bio": "Hi! My name is Caryn, and I am blessed! I am grateful to be daughter of the King of Kings, wife of Truman (who still makes me laugh out loud every day after 20 years of marriage!), and mom of four precious kids: Jack, Kate, Ellie, and Annie. I have a weird memory for dates, names, and faces that has gotten me called a \"stalker\" by my children. I love to laugh, take pictures, and hate public restrooms. I can honestly say that I have no greater joy than to hear of my children walking in the truth.",
  "key_verse": "But now in Christ Jesus you who were once far off have been brought near by the blood of Christ. For he himself is our peace, who has made us both one and has broken down in his flesh the dividing wall of hostility. (Ephesians 2:13-14)",
  "central_truth": "Even though we sometimes may feel like outsiders, God's Word is clear that we are chosen and dearly loved!",
  "reflections": "Try to imagine how the Christian Gentiles felt around the Jews during the early days of the Church. Previously, there had been a real distinction between Jew and Gentile. To the Jews, Gentiles were the \"Uncircumcised,\" \"heathens,\" and \"unclean.\" They were outsiders — the second class citizens of the spiritual community. This passage of Scripture shows how Jesus revolutionized their relationship with God and with their new brothers and sisters, the Jewish Christians. Jesus had \"broke(n) down the barrier of the dividing wall\" (Ephesians 2:14) and made the Jews and Gentiles into one Body. They were now all legitimate children of God.<br><br>Like the Gentiles of the early Church, I have known what it feels like to be an outsider and to be excluded from a group. It hurts. As a mother, it is especially painful to watch my children deal with the inevitable feelings of rejection that come about at different times in each of their lives. God's Word is a great encouragement to us when we feel like outsiders. Today, we read that \"in Christ Jesus you who formerly were far off have been brought near by the blood of Christ\" (Ephesians 2:13). No matter how we <em>feel, </em>the TRUTH is that we, as believers in Christ Jesus, are insiders! Christ, by His blood, has made it so! In fact, God's Word tells us that in Christ, we are:<br><br>• members of a chosen race, a royal priesthood (1 Peter 2:9);<br>• chosen of God, holy and beloved (Colossians 3:12);<br>• sons of God through faith in Christ Jesus (Galatians 3:26);<br>• fellow heirs with Christ (Romans 8:17);<br>• partakers of a heavenly calling (Hebrews 3:1); and<br>• members of His household (Ephesians 2:19, NIV)<br><br>Because Jesus Christ is your Lord, you are definitely not an outsider, but an insider! And unlike our feelings or the affections of man, this truth will never change!",
  "discussion_questions": "1. Do you put more stock in your feelings or in what God's Word says is true about who you are in Christ?<br><br> 2. When you feel discouraged or rejected, how can God's Word encourage you?<br> <br> 3. Can you think of a friend or relative who needs to be reminded today of the truth of who he or she is in Christ? Will you share it with him/her?<br>",
  "memory_verses": "<h4>Ephesians 2:8-10 – Saved by Grace</h4>For by grace you have been saved through faith; and that not of yourselves, it is the gift of God; not as a result of works, so that no one may boast. For we are His workmanship, created in Christ Jesus for good works, which God prepared beforehand so that we would walk in them.",
  "web_url": "//www.jointhejourney.com/log/88095",
  "previous_day": "2014-05-01",
  "next_day": "2014-05-05"
}

There's one more small thing I can think of. I noticed that the days_example.json response included the links for the footnotes inline with the passage, but not the actual formatted footnotes at the end of the passage (like this API request does: http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Ephesians2:11-22&include-passage-references=false&include-audio-link=false). It'd be nice to get the passage footnotes either as another parameter (as an array) in the Scripture object, or just include the footnotes in the passage's HTML string. The former is preferred if possible, but the latter is fine too.