Request for comment on new awe.sm API feature: multi-variate fields
7 views
Skip to first unread message
Jonathan Strauss
May 31, 2012, 7:40:48 PM5/31/12
to awes...@googlegroups.com
Hi all,
We're getting close to the release of an exciting new awe.sm API feature and would love to get your feedback as we finalize the details. In addition to the structured metadata you can associate with each awe.sm-powered tracking link (e.g. channel, tool, user_id, etc), we know that many of you want more arbitrary fields that can be defined specific to your application and are queryable via our Stats API. We have also had the request to support multi-variate fields, i.e. fields that support storing and querying within an array of values instead of just a single value.
To meet these needs, we are preparing to roll out 4 new multi-variate tag fields ('tag_2', 'tag_3', 'tag_4', and 'tag_5') AND we're going to add multi-variate support to the existing 'tag' field. We'd like to get your feedback on the following proposals for how these changes will work:
A) You can choose to store a single value OR multiple values in a given tag field
B) Multiple values for a given field must be specified using an HTTP array (e.g. http://api.awe.sm/url.json?v=3&key=KEY&tag_2[]=val1&tag_2[]=val2)
C) If a single value is specified, the value is limited to 255 characters (anything beyond 255 characters will be trimmed); if multiple values, the total values from the HTTP are limited to 255 characters (all values that exceed 255 characters will be ignored)
D) We will be storing the multiple values specified using an HTTP array in JSON array form, so any single variables specified (or already existing) in JSON array form will be treated the same as multiple values
E) All matching, including on multiple values, will continue to be case-sensitive
F) The order in which multiple values are submitted in the HTTP array will be preserved (e.g. ["$AAPL","$GOOG"] != ["$GOOG", "$AAPL"])
G) Filtering for a single value within an array of values for a given tag field will take the form %field%[]=%filter value% (e.g. 'http://api.awe.sm/stats/range.json?v=3&key=KEY&tag_2[]=foobar')
H) Standard grouping (and pivoting) will be less useful on a field with an array of values since the grouping will be done on the full JSON array in which the raw data is stored (ordered and case-sensitive)
I) We may add special-case grouping (and maybe pivoting) across the multiple values within an array using the form group_by=%field%_array (e.g. 'http://api.awe.sm/stats/range.json?v=3&key=KEY&group_by=tag_2_array'); this would return duplicate counts for any awesm_urls that were tagged with >1 value in the field by which they're being grouped
We're getting close to the release of an exciting new awe.sm API feature and would love to get your feedback as we finalize the details. In addition to the structured metadata you can associate with each awe.sm-powered tracking link (e.g. channel, tool, user_id, etc), we know that many of you want more arbitrary fields that can be defined specific to your application and are queryable via our Stats API. We have also had the request to support multi-variate fields, i.e. fields that support storing and querying within an array of values instead of just a single value.
To meet these needs, we are preparing to roll out 4 new multi-variate tag fields ('tag_2', 'tag_3', 'tag_4', and 'tag_5') AND we're going to add multi-variate support to the existing 'tag' field. We'd like to get your feedback on the following proposals for how these changes will work:
A) You can choose to store a single value OR multiple values in a given tag field
B) Multiple values for a given field must be specified using an HTTP array (e.g. http://api.awe.sm/url.json?v=3&key=KEY&tag_2[]=val1&tag_2[]=val2)
C) If a single value is specified, the value is limited to 255 characters (anything beyond 255 characters will be trimmed); if multiple values, the total values from the HTTP are limited to 255 characters (all values that exceed 255 characters will be ignored)
D) We will be storing the multiple values specified using an HTTP array in JSON array form, so any single variables specified (or already existing) in JSON array form will be treated the same as multiple values
E) All matching, including on multiple values, will continue to be case-sensitive
F) The order in which multiple values are submitted in the HTTP array will be preserved (e.g. ["$AAPL","$GOOG"] != ["$GOOG", "$AAPL"])
G) Filtering for a single value within an array of values for a given tag field will take the form %field%[]=%filter value% (e.g. 'http://api.awe.sm/stats/range.json?v=3&key=KEY&tag_2[]=foobar')
H) Standard grouping (and pivoting) will be less useful on a field with an array of values since the grouping will be done on the full JSON array in which the raw data is stored (ordered and case-sensitive)
I) We may add special-case grouping (and maybe pivoting) across the multiple values within an array using the form group_by=%field%_array (e.g. 'http://api.awe.sm/stats/range.json?v=3&key=KEY&group_by=tag_2_array'); this would return duplicate counts for any awesm_urls that were tagged with >1 value in the field by which they're being grouped
We are really excited to get this out to you ASAP and appreciate any and all feedback you may have on the approach and especially the proposed syntax (i.e. are our choices clear and self-explanatory?). You can reply to this message or directly to devel...@awe.sm.
Thanks!
-jonathan
--
Jonathan Strauss, Co-Founder
We're hiring! http://awe.sm/jobs
Twitter: http://twitter.com/jhstrauss
Reply all
Reply to author
Forward
0 new messages