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.sba.gov/cs/content.json&before=2012-04-12&type=page

You must be authenticated by SBA.gov to use this API.

2. Query Language

Query your data in the following format:
www.sba.gov/cs/content.json&YourQuery

cs: This is the API name set up in the Services module on the host site (www.sba.govin 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 SBA.gov before 2012-04-12 with the field "location" you would write "before=2012-04-12&type=page&field=location".
www.sba.gov/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.sba.gov/cs/content.xml&YourQuery

4. Instructions for returning specific content

To return all content with last edit before 2012/04/12:
www.sba.gov/cs/content.json&before=2012-04-12or
www.sba.gov/cs/content.json&before=2012-nov-12.

To return all content with last edit after 2012/04/12:
www.sba.gov/cs/content.json&after=2012-04-12.

To return only content of a certain type or types:
www.sba.gov/cs/content.json&type=pageor
www.sba.gov/cs/content.json&type=page+story.

To limit the number of output hits in queries with other terms:
www.sba.gov/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.sba.gov/cs/content.json&type=mycustomcontent&field=mycustomfield

To return two or more custom field:
www.sba.gov/cs/content.json&type=mycustomcontent&field=mycustomfield+yourcustomfield

To sort the query output on the last edit date in ascending or descending order:
www.sba.gov/cs/content.json&after=2012-04-12&limit=50&sort=ascor
www.sba.gov/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.sba.gov/cs/content.json&after=2012-04-12&batch=1

To get the second batch:
www.sba.gov/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.sba.gov before 2012-04-12 with the field "location" you would query using "before=2012-04-12&type=page&field=location."

Learn more at
www.sba.gov/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.sba.gov/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.sba.gov/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 requires authentication. Participants must get a UID/PWD before using the API. Please contact websupport@sba.gov if you would like to get credentials. 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.sba.gov/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.sba.gov/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.