[blipit] r160 committed - Created wiki page describing the BlipIt RESTful web services.
bli...@googlecode.com
Author: kalyan.akella
Date: Sun Jan 16 00:05:27 2011
Log: Created wiki page describing the BlipIt RESTful web services.
http://code.google.com/p/blipit/source/detail?r=160
Added:
/wiki/RestfulBlipIt.wiki
=======================================
--- /dev/null
+++ /wiki/RestfulBlipIt.wiki Sun Jan 16 00:05:27 2011
@@ -0,0 +1,337 @@
+#summary Introduction to the RESTful APIs of BlipIt
+
+= Introduction =
+
+All the functionality of !BlipIt is exposed as a set of RESTful web
services. We use the HTTP protocol with JSON transport for client-server
communication. The following sections describe how every resource
in !BlipIt can be manipulated using these web services.
+
+= !BlipIt Resources =
+
+All resources exposed in !BlipIt require their _category_ to be specified.
Currently _panic_ and _ad_ are the only supported categories.
+
+== Channel ==
+
+Following operations are permitted on a _channel_:
+
+ * *URL*: http://blipitsvc.appspot.com/blipit/{category}/channel
+ * *HTTP Method*: GET
+ * *Purpose*: Lists all the _channels_ available for the specified
_*category*_.
+ * Sample Output for http://blipitsvc.appspot.com/blipit/panic/channel:
+ {{{
+ [
+ {
+ key: {
+ kind: "Channel",
+ id: 1
+ },
+ name: "fire",
+ category: {
+ category: "PANIC"
+ }
+ },
+ {
+ key: {
+ kind: "Channel",
+ id: 2
+ },
+ name: "accident",
+ category: {
+ category: "PANIC"
+ }
+ }
+ ]
+ }}}
+
+ * *URL*: http://blipitsvc.appspot.com/blipit/{category}/channel
+ * *HTTP Method*: POST
+ * *Purpose*: Creates a new channel in the specified _*category*_.
+ * Sample Input for http://blipitsvc.appspot.com/blipit/ad/channel:
+ {{{
+ {
+ name: "retail",
+ category: {
+ category: "AD"
+ }
+ }
+ }}}
+
+ * *URL*:
http://blipitsvc.appspot.com/blipit/{category}/channel/{channel_id}
+ * *HTTP Method*: GET
+ * *Purpose*: Retrieves the channel with the ID specified by
_*channel_id*_ belonging to the specified _*category*_.
+ * Sample Output for http://blipitsvc.appspot.com/blipit/panic/channel/2:
+ {{{
+ {
+ key: {
+ kind: "Channel",
+ id: 2
+ },
+ name: "accident",
+ category: {
+ category: "PANIC"
+ }
+ }
+ }}}
+
+== Blip ==
+
+Following operations are permitted on a _blip_:
+
+ * *URL*: http://blipitsvc.appspot.com/blipit/{category}/blip
+ * *HTTP Method*: GET
+ * *Purpose*: Lists all the _blips_ available for the specified
_*category*_.
+ * Sample Output for http://blipitsvc.appspot.com/blipit/panic/blip:
+ {{{
+ [
+ {
+ key: {
+ kind: "Blip",
+ id: 57001
+ },
+ title: "Diamond District Rentals",
+ description: "20% Off on 2 BHK Rentals",
+ geoPoint: {
+ latitude: 12.960169,
+ longitude: 77.64212
+ },
+ channelKeys: [
+ {
+ kind: "Channel",
+ id: 12001
+ },
+ {
+ kind: "Channel",
+ id: 8001
+ },
+ {
+ kind: "Channel",
+ id: 10001
+ }
+ ]
+ },
+ {
+ key: {
+ kind: "Blip",
+ id: 58001
+ },
+ title: "TGIF Hotel Discount",
+ description: "50% Off on Italian Pasta",
+ geoPoint: {
+ latitude: 12.960508,
+ longitude: 77.64375
+ },
+ channelKeys: [
+ {
+ kind: "Channel",
+ id: 9001
+ },
+ {
+ kind: "Channel",
+ id: 11001
+ }
+ ]
+ }
+ ]
+ }}}
+
+ * *URL*: http://blipitsvc.appspot.com/blipit/{category}/blip
+ * *HTTP Method*: POST
+ * *Purpose*: Creates a new blip in the specified _*category*_.
+ * Sample Input for http://blipitsvc.appspot.com/blipit/panic/blip:
+ {{{
+ {
+ title: "Panic Message",
+ description: "Panic Message from 895396",
+ geoPoint: {
+ latitude: 12.960169,
+ longitude: 77.64212
+ },
+ channelKeys: [
+ {
+ id: 12001
+ },
+ {
+ id: 8001
+ },
+ {
+ id: 10001
+ }
+ ],
+ creatorId: "895396"
+ }
+ }}}
+
+ * *URL*: http://blipitsvc.appspot.com/blipit/{category}/blip/{blip_id}
+ * *HTTP Method*: GET
+ * *Purpose*: Retrieves the blip with the ID specified by _*blip_id*_
belonging to the specified _*category*_.
+ * Sample Output for http://blipitsvc.appspot.com/blipit/panic/blip/58001:
+ {{{
+ {
+ key: {
+ kind: "Blip",
+ id: 58001
+ },
+ title: "TGIF Hotel Discount",
+ description: "50% Off on Italian Pasta",
+ geoPoint: {
+ latitude: 12.960508,
+ longitude: 77.64375
+ },
+ channelKeys: [
+ {
+ kind: "Channel",
+ id: 9001
+ },
+ {
+ kind: "Channel",
+ id: 11001
+ }
+ ]
+ }
+ }}}
+
+ * *URL*: http://blipitsvc.appspot.com/blipit/{category}/blip/{blip_id}
+ * *HTTP Method*: DELETE
+ * *Purpose*: Deletes the blip with the ID specified by _*blip_id*_
belonging to the specified _*category*_.
+
+== Filter ==
+
+A _filter_ captures a set of criteria used while retrieving blips.
Following operations are permitted on a _filter_:
+
+ * *URL*: http://blipitsvc.appspot.com/blipit/{category}/filter
+ * *HTTP Method*: GET
+ * *Purpose*: Lists all the _filters_ available for the specified
_*category*_.
+ * Sample Output for http://blipitsvc.appspot.com/blipit/ad/filter:
+ {{{
+ [
+ {
+ key: {
+ kind: "Filter",
+ id: 60001
+ },
+ radius: 2000,
+ geoPoint: {
+ latitude: 12.968666,
+ longitude: 77.5795
+ },
+ channelKeys: [
+ {
+ kind: "Channel",
+ id: 12001
+ },
+ {
+ kind: "Channel",
+ id: 8001
+ },
+ {
+ kind: "Channel",
+ id: 10001
+ }
+ ]
+ },
+ {
+ key: {
+ kind: "Filter",
+ id: 61001
+ },
+ radius: 10000,
+ geoPoint: {
+ latitude: 12.968666,
+ longitude: 77.5795
+ },
+ channelKeys: [
+ {
+ kind: "Channel",
+ id: 9001
+ },
+ {
+ kind: "Channel",
+ id: 50001
+ }
+ ]
+ }
+ ]
+ }}}
+
+ * *URL*: http://blipitsvc.appspot.com/blipit/{category}/filter
+ * *HTTP Method*: POST
+ * *Purpose*: Creates a new filter in the specified _*category*_.
+ * Sample Input for http://blipitsvc.appspot.com/blipit/ad/filter:
+ {{{
+ {
+ radius: 10000,
+ geoPoint: {
+ latitude: 12.968666,
+ longitude: 77.5795
+ },
+ channelKeys: [
+ {
+ kind: "Channel",
+ id: 9001
+ },
+ {
+ kind: "Channel",
+ id: 50001
+ }
+ ]
+ }
+ }}}
+
+ * *URL*:
http://blipitsvc.appspot.com/blipit/{category}/filter/{filter_id}
+ * *HTTP Method*: GET
+ * *Purpose*: Retrieves all the blips matching the criteria given by the
filter with the ID specified by _*filter_id*_.
+ * Sample Output for http://blipitsvc.appspot.com/blipit/ad/filter/61001:
+ {{{
+ [
+ {
+ key: {
+ kind: "Blip",
+ id: 57001
+ },
+ title: "Diamond District Rentals",
+ description: "20% Off on 2 BHK Rentals",
+ geoPoint: {
+ latitude: 12.960169,
+ longitude: 77.64212
+ },
+ channelKeys: [
+ {
+ kind: "Channel",
+ id: 12001
+ },
+ {
+ kind: "Channel",
+ id: 8001
+ },
+ {
+ kind: "Channel",
+ id: 10001
+ }
+ ]
+ },
+ {
+ key: {
+ kind: "Blip",
+ id: 58001
+ },
+ title: "TGIF Hotel Discount",
+ description: "50% Off on Italian Pasta",
+ geoPoint: {
+ latitude: 12.960508,
+ longitude: 77.64375
+ },
+ channelKeys: [
+ {
+ kind: "Channel",
+ id: 9001
+ },
+ {
+ kind: "Channel",
+ id: 11001
+ }
+ ]
+ }
+ ]
+ }}}
+
+ * *URL*:
http://blipitsvc.appspot.com/blipit/{category}/filter/{filter_id}
+ * *HTTP Method*: DELETE
+ * *Purpose*: Deletes the filter with the ID specified by _*filter_id*_
belonging to the specified _*category*_.