Content Share

The Content Share module is designed to serve any Drupal site's content via a URL. A content consumer can initiate a transfer by a simple http request. This can be done from a client application or in a browser. The content from the originating site is returned in JSON, XML and other formats, enabled via the Services module.

Introduction

This module can be used to build a number of features on your Drupal site. Examples include (a) serving content from one Drupal site to several read-only sites, that do not have to be in Drupal, (b) consuming data from a Drupal site in a manner similar to newsfeeds, (c) migrating data from a Drupal site (this can be useful for a Drupal 6 to 7 to 8 migration, for instance), etc. Technically, this module is an API for any or all of the site's content with a simple and powerful query language.

Authentication is optional. It can be required or disabled by the admin of the host site (YourDrupalSite). If Authentication is “on” the consumer client will be required to provide a login/password pair. These can be obtained by registering at the host Drupal site (YourDrupalSite). If Authentication is “off” content will be served to the anonymous user with anonymous permissions. See "AUTHENTICATION" section below on details of how to authenticate a client.

Admin settings allow to choose what content types and fields will be served.

Content Share returns JSON or XML, or other formats enabled in the Services module. Content Share extends Services to create an API endpoint and to format output. It handles input parsing, security, data querying, and other aspects of serving content via a URL.

Content Share depends on Services, Content, Chaos tools, and, if search is enabled, on Apachesolr.

The Content Share development is supported as part of www.SBA.gov site development at www.REIsystems.com. Documentation written in part by Nico Janssen.

List of Features

1. Intuitive and Flexible URL Query language
2. Drupal Session Authentication or Anonymous Querying depending on admin settings at ./admin/settings/content_share
3. User access to the API controlled by role for authenticated users
4. Admin settings of what content types and fields to expose to the consumer, logged and anonymous
5. Usage Logs and Stats
6. Solr Search Integration
7. Error Reporting and Tracking
8. Security Heuristics for Query Handling
9. Batch download for big data
10. Size of download estimate

Content Share API Documentation

Table of Contents:
1. Summary
2. Query language
3. Query terms
4. Instructions for returning specific content
5. Error handling
6. Authentication and steps

1. Summary

The Content Share module is designed to serve a Drupal site's content and custom data via a URL. A content consumer can initiate a transfer by calling a URL either from a browser or client application. The URL on the host site takes intuitive and flexible query requests. Here is an example: www.mysite.com/cs/content.json&before=2012-04-12&type=page

2. Query Language

Query your data in the following format:
www.mysite.com/cs/content.json&YourQuery
cs: This is the API name set up in the Services module on the host site (www.mysite.comin this case).
YourQuery: "query term" = "query string"

3. Query Terms

• before: Last edited on or before a date. The date can be specified as year-month-day or year-month. Note that entering year alone will cause an error.
• after: Last edited on or after a date. The date can be specified as year-month-day or year-month. Note that entering year alone will cause an error.
• type: Types can be given as a singular type, type, e.g. type=story or as a plural, e.g. type=story + page. These types are machine-readable, and they typically do not contain spaces.
• search: Solr search. This takes a query term. This will work only if CS Solr module is enabled and set up on the host site.
• limit: The number of hits to return. This can be overridden in host site admin settings to avoid server time-outs.
• field: Custom field(s) to be included in output along with default fields. They can be singular, e.g. field=myfield or plural, e.g. field=myfield+yourfield. Each field should be the machine-readable name of the file you would like to see in the output. Typically these names contain no white spaces.
• sort: Sorts on the created date and can take values "asc" for ascending sorting or "desc" for descending.
• batch: Batches have possible values of 1, 2, 3 and higher. For larger data, batches will return consecutive batches of size set in Batch Size.
• size: There is only one possible value of 'size.' size=size returns ONLY the number of hits in your query. This is to estimate the size of your return prior to requesting it in full.
• help: Returns a list of available content types and fields as well as a help message and a URL for further reference

Mixing and Matching Query Terms
Query terms can be mixed and matched in any order with the exception of limit with batch. For example, to get all content of type "page" created on Mysite.com before 2012-04-12 with the field "location" you would write "before=2012-04-12&type=page&field=location".
www.mysite.com/cs/content.json&before=2012-04-12&type=page&field=location

Output Format
For all queries either JSON or XML output format can be specified. To return XML the query will state: www.mysite.com/cs/content.xml&YourQuery

4. Instructions for returning specific content

To return all content with last edit before 2012/04/12:
www.mysite.com/cs/content.json&before=2012-04-12or
www.mysite.com/cs/content.json&before=2012-nov-12.
To return all content with last edit after 2012/04/12:
www.mysite.com/cs/content.json&after=2012-04-12.
To return only content of a certain type or types:
www.mysite.com/cs/content.json&type=pageor
www.mysite.com/cs/content.json&type=page+story.
To limit the number of output hits in queries with other terms:
www.mysite.com/cs/content.json&after=2012-04-12&limit=50.
This option will output only 50 hits sorted by the most recent unless the sort is set to "asc" (ascending)
To return a custom (CCK) field:
www.mysite.com/cs/content.json&type=mycustomcontent&field=mycustomfield
To return two or more custom field:
www.mysite.com/cs/content.json&type=mycustomcontent&field=mycustomfield+...
To sort the query output on the last edit date in ascending or descending order:
www.mysite.com/cs/content.json&after=2012-04-12&limit=50&sort=ascor
www.mysite.com/cs/content.json&after=2012-04-12&limit=50&sort=desc
To download large volumes of data that would otherwise time-out the host server, use the batch mode.
It can be combined with all other terms with the exception of "limit". The batch size is set by administrators of the host site.
To get the first batch:
www.mysite.com/cs/content.json&after=2012-04-12&batch=1
To get the second batch:
www.mysite.com/cs/content.json&after=2012-04-12&batch=2
For the third batch and above, simply follow this URL method by adding "3" to the end of the URL.
A client can use a recursive function to query the API incrementally until no more content is returned. Query terms can be mixed and matched in any order with the exception of the batch limit. Batch limits are set on the host site. For example, to get all content with the "page" type created on www.mysite.com before 2012-04-12 with the field "location" you would query using "before=2012-04-12&type=page&field=location."
Learn more at
www.mysite.com/cs/content.json&before=2012-04-12&type=page&field=location
To get the number of hits in your query (without the hits themselves), visit:
www.mysite.com/cs/content.json&after=2012-04-12&size=size
This will return only "size":'Number of hits on your site' "
To get a list of available content types and fields as well as a URL for further reference, visit:
www.mysite.com/cs/content.json&help=help. This will return only the help info.

5. Error Handling

If the query returns results in an error, the output will, in most cases, contain an error:error pair and a detailed error message.

6. Authentication

The API can be set to require authentication or to server to an anonymous user. If you use a software client to consume the content and the admin of the host site has set an authentication requirement, you will need to provide an authentication mechanism in the client.

Authentication Steps
1. Submit a request for credentials and obtain a login/password pair.
2. From your client, make a call to: www.mysite.com/cs/user/login
with the login/password included in the POST request and the format set to e.g. JSON
$user_data = array(
'username' => 'my_user_name',
'password' => 'my_password',);
array('Accept: application/json')
This can be accomplished with cURL or any other module/class for URL calls depending on the programming language and your preferences.
3. Wait for the server response. If it is 200, extract a cookie for future authentication requests.
This can be done in PHP and JSON as follows:
$logged_user = json_decode($response);
$cookie_session = $logged_user->session_name . '=' . $logged_user->sessid;
4. Query Content Share over the usual URL (www.mysite.com/cs/content.json&YourQuery) and provide the $cookie_sessionin your headers.
Further details and a sample client code can be found at http://drupal.org/node/910598.