Resource Share

Introduction

This module can be used to build a number of features on your Drupal site. Possible examples include (a) serving content from one Drupal site to one or more sites that do not have to be Drupal, (b) feeding data into mobile applications, (c) customizing site views using client-side javascript, (d) migrating data from a Drupal site (this can be useful for a Drupal 7 to 8 migration, for instance), etc. Technically, this module is an API for any or all of the site's content and any data in the database with a simple and powerful query language.

Authentication is optional. It can be required or disabled by the admin of the host site. 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 all anonymous users. See "AUTHENTICATION" section below on details of how to authenticate a client.

Admin settings allow to choose content types and fields as well as database tables that you want to make accessible via this module.

Resource Share returns JSON or XML, or other formats enabled in the Services module. Resource 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.

Resource Share depends on Services, Content, and Chaos tools.

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, fields, and db tables to expose to the consumer, logged and anonymous
5. Error Reporting and Tracking
6. Security Heuristics for Query Handling
7. Batch download for big data
8. Size of download estimate
9. direct db queries

Resource 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 Resource 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/rs/share/before=2012-04-12&type=page

2. Query Language

Query your data in the following format:
www.mysite.com/rs/share/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.
• 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
• table: Returns data from a database table, custom or Drupal core, with fields listed in the "fields" term.

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/rs/share/before=2012-04-12&type=page&field=location

Output Format
For all queries either JSON, XML or any other Services 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/rs/share/before=2012-04-12.json or
www.mysite.com/rs/share/before=2012-nov-12.json
To return all content with last edit after 2012/04/12:
www.mysite.com/rs/share/after=2012-04-12.json
To return only content of a certain type or types:
www.mysite.com/rs/share/type=page.json or
www.mysite.com/rs/share/type=page+story.json
To limit the number of output hits in queries with other terms:
www.mysite.com/rs/share/after=2012-04-12&limit=50.json
This option will output only 50 hits sorted by the most recent unless the sort is set to "asc" (ascending)
To return a custom field:
www.mysite.com/rs/share/type=mycustomcontent&field=mycustomfield
To return two or more custom field:
www.mysite.com/rs/share/type=mycustomcontent&field=mycustomfield+yourcus...
To sort the query output on the last edit date in ascending or descending order:
www.mysite.com/rs/share/after=2012-04-12&limit=50&sort=asc.json or
www.mysite.com/rs/share/after=2012-04-12&limit=50&sort=desc.json
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/rs/share/after=2012-04-12&batch=1.json
To get the second batch:
www.mysite.com/rs/share/after=2012-04-12&batch=2.json
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/rs/share/before=2012-04-12&type=page&field=location.json
To get the number of hits in your query (without the hits themselves), visit:
www.mysite.com/rs/share/after=2012-04-12&size=size.json
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/rs/share/help=help. This will return only the help info.
To query a database table, custom or Drupal core, use
www.mysite.com/rs/table=nomination_email_poc&fields=office_code+office_n...

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/rs/share/YourQuery) and provide the $cookie_sessionin your headers.
Further details and a sample client code can be found at http://drupal.org/node/910598.

If you are looking for Drupal 6 version of this module, visit this project.

Supported in part by http://advantexcorp.com