Public JSON API section: add petition content endpoints and information about CORS vs. JSONP

source/includes/json/_bulk_data_columns.md

@@ -17,6 +17,9 @@ id,petition_id,email,first_name,last_name,phone_number,postcode,created_at,join_
 
 `GET https://demo.controlshiftlabs.com/api/bulk_data/schema/columns?table=signatures`
 
+- × CORS not supported
+- × JSONP not supported
+
 #### Query Parameters
 
 Parameter |  Description

source/includes/json/_bulk_data_schema.md

@@ -44,4 +44,7 @@ If the _Compress bulk data exports_ option is enabled, the extra `compression_fo
 
 `GET https://demo.controlshiftlabs.com/api/bulk_data/schema.json`
 
+- × CORS not supported
+- × JSONP not supported
+
 <div></div>

source/includes/json/_calendar.md

@@ -36,4 +36,8 @@ This retrieves a JSON object representing a calendar.
 `GET https://demo.controlshiftlabs.com/calendars/slug.json`
 
 Where slug is the slug of the calendar you're retrieving. 
+
+- × CORS not supported
+- ✓ JSONP supported
+
 <div></div>

source/includes/json/_categories_list.md

@@ -45,6 +45,9 @@ This retrieves a JSON array of category objects.
 
 `GET https://demo.controlshiftlabs.com/categories.json`
 
+- × CORS not supported
+- ✓ JSONP supported
+
 #### Working Example
 
 View and edit a working example on codepen.io:

source/includes/json/_category_petitions.md

@@ -153,6 +153,9 @@ This retrieves a paginated list of petitions in a category.
 
 `GET https://demo.controlshiftlabs.com/categories/<category slug>.json`
 
+- &times; CORS not supported
+- &check; JSONP supported
+
 #### Query Parameters
 
 Parameter | Default | Description

source/includes/json/_effort_petitions.md

@@ -141,6 +141,9 @@ Additionally, successful petitions will have the `successful` attribute set to `
 
 `GET https://demo.controlshiftlabs.com/efforts/<effort slug>.json`
 
+- &times; CORS not supported
+- &check; JSONP supported
+
 Parameter | Default | Description
 --------- | ------- | -----------
 effort slug | null | string - required - submitted as a part of the endpoint path, not as a separate URL parameter

source/includes/json/_effort_petitions_near.md

@@ -57,6 +57,9 @@ Depending on how the effort is configured, you can search either by location, or
 
 `GET https://demo.controlshiftlabs.com/efforts/<effort slug>/lookup/query.json`
 
+- &times; CORS not supported
+- &check; JSONP supported
+
 #### Query Parameters
 
 Parameter | Required? | Description

source/includes/json/_efforts_list.md

@@ -36,4 +36,7 @@ This JSON endpoint returns a paginated list of all Efforts and Landing Pages on
 
 `GET https://demo.controlshiftlabs.com/efforts.json`
 
+- × CORS not supported
+- × JSONP not supported
+
 <div></div>

source/includes/json/_featured_petitions.md

@@ -158,6 +158,9 @@ This retrieves a JSON object compliant with the [JSON API](http://jsonapi.org/)
 
 `GET https://demo.controlshiftlabs.com/petitions/featured.json`
 
+- × CORS not supported
+- ✓ JSONP supported
+
 #### Query Parameters
 
 Parameter | Default | Description

source/includes/json/_intro.md

@@ -1,16 +1,38 @@
 # JSON API Endpoints
 
-The JSONP API is a simple way to embed ControlShift petition content in external sites. It's intended for use by a front-end developer to embed content on web pages outside of the platform.  For example, a developer could:
+The public JSON API is a simple way to access non-sensitive ControlShift data.
+Many of the JSON API endpoints are intended for use by a front-end developer to embed content on web pages outside of the platform.
+For example, a developer could:
 
 * Show petitions
 * Allow a user to search for near by petitions
 * List petition categories
 * Show petitions within an effort
 
-Many of the endpoints can be consumed as JSONP instead of JSON by adding callback or variable parameters to the URLs.
-
-The URL slugs through the API are the same as those that are used through the web to represent specific petitions or categories.  Many front-end libraries including jQuery make it easy to consume JSONP endpoints. Our examples below use jQuery to consume these resources.
+The URL slugs through the API are the same as those that are used through the web to represent specific petitions or categories.
 
 <aside class="success">
 These examples use the domain <code>demo.controlshiftlabs.com</code>. You'll need to replace this with the hostname of your instance.
 </aside>
+
+## Using the JSON API from an external site
+When one website includes a call to retrieve JSON data from another website, that is considered a **cross-origin** request.
+For security reasons, browsers usually block this type of request by default.
+There are two different ways to get around this restriction to allow calling public ControlShift JSON API endpoints from external sites: CORS and JSONP.
+The documentation for each endpoint indicates which options are supported.
+
+### CORS
+CORS allows the ControlShift platform to specify that certain URLs are allowed to be requested cross-origin from certain domains.
+
+For JSON requests relying on CORS to work, you'll need to configure the allowed domains from **Settings > Integrations > CORS Hostnames**.
+Once a hostname is safe-listed there, any of the endpoints that support CORS can be used on pages on that domain.
+
+For example, to embed petition content from a ControlShift website **demo.controlshiftlabs.com** on your external website **hq.example.org**,
+you'd want to add **hq.example.org** to your CORS Hostnames.
+
+### JSONP
+JSONP is an older way to allow cross-origin requests for JSON data.
+The way it works is by specifying a Javascript callback that will handle the JSON data. The server wraps that callback around the data it returns.
+This allows the call to technically be a Javascript request instead of a JSON request, and so the browser allows it.
+
+Many front-end libraries, including jQuery, make it easy to consume JSONP endpoints. Our examples below use jQuery when demonstrating JSONP calls.

source/includes/json/_local_details.md

@@ -54,6 +54,9 @@ It can be used alongside the `/api/local/points` endpoint; the criteria for incl
 
 `GET https://demo.controlshiftlabs.com/api/local.json`
 
+- × CORS not supported
+- × JSONP not supported
+
 #### Query Parameters
 
 Parameter | Default | Description

source/includes/json/_local_points.md

@@ -42,4 +42,8 @@ This JSON endpoint returns a complete list of latitude/longitude coordinates for
 #### HTTP Request
 
 `GET https://demo.controlshiftlabs.com/api/local/points.json`
+
+- × CORS not supported
+- × JSONP not supported
+
 <div></div>

source/includes/json/_partnership_petitions.md

@@ -154,6 +154,9 @@ This retrieves a paginated list of petitions in a partnership.
 
 `GET https://demo.controlshiftlabs.com/partnerships/<partnership slug>/petitions.json`
 
+- &times; CORS not supported
+- &check; JSONP supported
+
 #### Query Parameters
 
 Parameter | Default | Description

source/includes/json/_petition_content.md

@@ -0,0 +1,34 @@
+### Get petition content
+
+```js
+fetch('https://demo.controlshiftlabs.com/api/petitions/repair-the-yellow-brick-road-1/what.json')
+  .then((response) => {
+    response.json().then((jsonData) => {
+      console.log(jsonData)
+    })
+  })
+```
+
+> JSON response
+
+```json
+{
+  "plain_text": "The Yellow Brick Road has been neglected. Commit to repairing the damaged sections of the road in the next year!",
+  "rich_text": "<div>The <strong>Yellow Brick Road</strong> has been neglected. <em>Commit to repairing the damaged sections of the road in the next year!</em></div>",
+}
+```
+
+Retrieve the formatted "What" or "Why" text of a petition.
+
+#### HTTP Request
+
+`GET https://demo.controlshiftlabs.com/api/petitions/<slug>/what.json`
+
+`GET https://demo.controlshiftlabs.com/api/petitions/<slug>/why.json`
+
+- &check; CORS supported
+- &times; JSONP not supported
+
+If the petition does not exist or is not visible to the public, the response will be 404 Not Found.
+
+<div></div>

source/includes/json/_petitions.md.erb

@@ -1,5 +1,6 @@
 ## Petitions
 
 <%= partial "includes/json/single_petition.md" %>
+<%= partial "includes/json/petition_content.md" %>
 <%= partial "includes/json/featured_petitions.md" %>
 <%= partial "includes/json/petitions_search.md" %>

source/includes/json/_petitions_search.md

@@ -130,6 +130,9 @@ This JSON endpoint allows you to build an interface where users can search throu
 
 `GET https://demo.controlshiftlabs.com/petitions/search.json`
 
+- × CORS not supported
+- ✓ JSONP supported
+
 #### Query Parameters
 
 Parameter | Default | Description

source/includes/json/_single_petition.md

@@ -74,6 +74,9 @@ This retrieves a single petition object.
 
 `GET https://demo.controlshiftlabs.com/petitions/<slug>.json`
 
+- &times; CORS not supported
+- &check; JSONP supported
+
 #### Query Parameters
 
 Parameter | Default | Description