Changes between Version 1 and Version 2 of WebServices

Timestamp:

01/26/11 12:48:08 (6 years ago)

Author:

jim

Comment:

added projects, tidied

WebServices

@@ -1 @@
-= Web Data Services =
+[[PageOutline(2-5, Table of Contents, floated)]]
+= Web Services =
 
-This page describes the web services and data provided by the main [http://www.transitionnetwork.org/ Transition Network] website and the [http://news.transitionnetwork.org/ Sharing Engine].
+This page describes the web services and data provided by the main [http://www.transitionnetwork.org/ Transition Network] website and the [http://news.transitionnetwork.org/ Sharing Engine]. They include
 
-== Directory Services ==
-
-These services provide lists of core ContentTypes that can be used to prime or update remote caches and clients. 
+'''Directory Services:''' Return directories of ContentTypes that can be used to prime or update remote caches and clients. 
+'''News Services:''' Return news stories for a given location, radius and type.
 
 
-=== Initiative Directory Service ===
+
+== Initiative Directory Service ==
 
 Returns a list of initiatives with their basic data and geographical coordinate information. See below for an example
@@ -16 +17 @@
  * '''Usage:''' To be used sparingly to prime remote cache of initiative data. Use 7 or 30 day update versions for refreshes. This view is cached for 6 hours to reduce performance impacts on the main site.
  * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/initiatives/all
- * '''Parameters:''' None, only three variations of this view exist - 'all' and updated within 7 or 30 days versions.
+ * '''Parameters:''' None, only three variations of this view exist - 'all' and updated within 7 or 30 days versions. The last segment of the URL changes for accordingly.
 
 
@@ -33 +34 @@
 
 
-==== Returned fields & sample output ====
+=== Returned fields & sample output ===
 '''Fields:''' See ContentTypes for a full description of the fields
  * nid - node id
  * url - directory page on Transition Network.org
  * title
+ * updated - timestamp in [http://www.w3.org/TR/NOTE-datetime W3C DTF]
  * initiative_community_types - multi-select option values
  * initiative_type - single-select option value
@@ -80 +82 @@
 }}}
 
+
+
+
+== Project Directory Service ==
+
+Broadly similar to the Initiative Directory Service, except returning Project data. See ContentTypes for a proper description of this.
+
+==== ALL Projects ====
+ * '''Returns:''' All projects in in the directory - see below for format and example output.
+ * '''Usage:''' To be used sparingly to prime remote cache of project data. Use 7 or 30 day update versions for refreshes. This view is cached for 6 hours to reduce performance impacts on the main site.
+ * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/projects/all
+ * '''Parameters:''' None, only three variations of this view exist - 'all' and updated within 7 or 30 days versions. The last segment of the URL changes for accordingly.
+
+
+==== Projects updated within 30 days ====
+
+As above except:
+ * '''Usage:''' To be used whenever a client needs to refresh their cache, unless the time since last update less than 7 days in which case use the version below, or more that 30 days in which case get ALL again. View cached for 6 hours.
+ * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/projects/updated-month
+
+
+==== Projects updated within 7 days ====
+
+As above except:
+ * '''Usage:''' To be used whenever a client needs to refresh their cache, unless the time since last update is more that 7 days in which case use month variant. View cached for 1 hour.
+ * '''Service URL''': http://www.transitionnetwork.org/transition-services/directories/projects/updated-week
+
+
+==== Returned fields & sample output ====
+'''Fields:''' See ContentTypes for a full description of the fields
+ * nid - node id
+ * url - directory page on Transition Network.org
+ * title
+ * updated - timestamp in [http://www.w3.org/TR/NOTE-datetime W3C DTF]
+ * project_start_date - date formatted for display (DD MMM YYYY)
+ * project_people_involved - formatted number
+ * websites - usually one, potentially several URLs representing the initiative 
+ * contact_primary_name - formatted string
+ * contact_primary_uid - user ID to be used to pull up contact pages on TN.org (thus maintaining privacy)
+ * location_city, location_province_name, location_country_name - strings for the address
+ * location_latitude, location_longitude - decimal coordinates representing geocoded position of imitative
+
+'''Example output:'''
+{{{
+{
+  "projects" : [
+    {
+      "project" : {
+        "nid" : "14779",
+        "url" : "https://www.transitionnetwork.org/projects/newport-fruit-vegie-swap",
+        "title" : "Newport Fruit & Vegie Swap",
+        "updated" : "2011-01-24T12:41:14+0000",
+        "project_start_date" : "14 Aug 2010",
+        "project_people_involved" : "4",
+        "websites" : "http://www.facebook.com/pages/Newport-fruit-and-vegie-swap/144892595545635?v=wal...",
+        "contact_primary_name" : "Kate Leslie",
+        "contact_primary_uid" : "3129",
+        "location_city" : "Newport",
+        "location_province_name" : "Victoria",
+        "location_country_name" : "Australia",
+        "location_latitude" : "-37.841581",
+        "location_longitude" : "144.874088"
+      }
+    }
+    [... repeats ...]
+  ]
+}
+}}}