Batch Feed Resource

The Feed resource is used to GET, PUT or DELETE stream data for one or more streams in the same call. Streams can belong to different components but have to be within the same organization.

Batching feed uploads and downloads are encouraged so as to decrease transaction costs and improve performance.

Interval, Random and Point Stream Samples
The Batch Feed resource is used for all stream types: random, interval and point.

The PUT API can be the same for all stream types:
  • Feeds contain a collection of datetime and value tuples. The server will place the correct values into the appropriate intervals for interval streams. The last datetime value will be used for point stream values.
  • Having a common PUT interface allows the component designer to decide how the data should be organized when it arrives into GroveStreams without having to make any modifications to the feed source.

The Get API varies slightly since:
  • Interval Stream feeds contain a collection of start datetime, end datetime and value tuples.
  • Random Stream samples contain a collection of datetime and value tuples
  • Point Stream samples contain a single value tuple. Think of a Point Stream as a Random Stream but only the last value is retained.



Appending and Historical Inserts
Only a PUT  (no POST) operations are allowed for feed sample inserts/updates. This is because the range of samples being inserted may or may not overwrite some existing samples in the store.

Gaps and Nulls

Nulls may be passed as sample values. JSON nulls indicate a gap interval for interval stream samples. JSON nulls for random samples will not be saved. Any time range  may be inserted/updated whether they overlap existing samples or not.

Sparcity
GroveStreams supports data sparsity. If a years worth of samples are inserted for 2008 and another year's worth of intervals are inserted for 2010, no data for 2009 will exist within the store. All gaps (nulls) will be returned if a feed interval request is for 2009. Also, if a request for intervals prior to 2008 or after 2010 occur, then all gaps will be returned for interval streams - an error will not be returned.

Dynamic Rollups - Interval Size Conversions during GET
Not all streams are interval streams, and even if they are, it is unlikely their interval sizes will be the same. There are times when streams need to be monitored, graphed or used in a derived interval stream calculations together. Ideally, we need all of the streams' cycle intervals to be the same time range for these types of operations. For these scenarios, a request cycle can be passed in and an interval size conversion (a dynamic rollup) can take place during the GET process if it doesn't require too many intervals to be retrieved from the store.

When a request cycle is passed in for a GET request and that cycle is not a base cycle for streams being requested or the stream is a random stream, GroveStreams will attempt to derive intervals optimally by leveraging the stream's rollup calendar whenever possible. The following rules are used during the optimizing process:
  • For Interval Streams:
    • If the request cycle matches the stream's base cycle then the base cycle intervals are returned
    • If the request cycle matches the one of the cycles in the stream's rollup calendar then the intervals for that rollup calendar are returned
    • If the request cycle does not match a stream's base cycle or any rollup cycles then the largest rollup cycle that fits evenly into the request cycle will be loaded and then rolled up dynamically to match the request cycle interval sizes
    • If the request cycle  does not match a stream's base cycle or any rollup cycles and no rollup cycles fit evenly into the request cycle but there is a rollup cycle that is larger than the request cycle then that large rollup cycle will be used to derive the smaller request cycle intervals by using the larger interval values for each smaller interval who's end datetime falls within the large cycle's interval time range.
    • If none of these conditions exist then an error will returned
  • For Random Streams:
    • Sample data is aggregated for each request cycle interval according to the random stream's default rollup method or the rollup method(s) passed into the request

For interval streams, if a request cycle is passed and cycles are included in the items parameter then those stream cycles will be used to derive intervals that match the request cycle interval sizes. This is useful for scenarios such as when you have a request cycle of "one day" intervals but you want to use "one month" interval values - set the request cycle to "days" and  pass in "months" as part of the stream parameter.

For random streams, if a request cycle is passed and cycles are included in the items parameter, the request cycle will be used and the item cycles will be ignored. 


Dynamic Component and Stream Creation

PUT feeds can automatically create components and streams that do not exist. See the PUT below for more information.


GET feed



Returns a collection of feeds for a specified time range. Returned feed data can include random stream samples, interval base intervals or a collection of interval statistics for a cycle range.
Resource Information
Rate Limited?
No
session, oauth and org tokens compatible?
Yes
api_key token token compatible?
Yes



Resource URL

http://grovestreams.com/api/feed

Parameters

startDate mandatory* The start datetime (UTC epoch millis) of the range request - inclusive. GroveStreams will round to the start of the interval it falls within for cycle requests. Optional if numIntvls and endDate is passed in.
endDate mandatory* The end datetime (UTC epoch mills) of the range request - exclusive. GroveStreams will round to the end of the interval it falls within for cycle requests.Optional if numIntvls and startDate is passed in.
intvlDates optional Set to "return" to include arrays containing the start and end datetimes for each interval within the returned JSON (UTC epoch millis). Random stream requests will return sample times.
ids optional Set to "return" in include the stream and component IDs within the returned JSON.
cycle optional The cycle being requested. If this argument is not included then an interval stream's base cycle intervals will be returned. If set to a cycle uid that is not an interval stream's base cycle and the stats argument is missing then the stream's default rollup method will be used to determine the set of statistics to retrieve. Including a cycle will convert random sample stream requests to intervals.
stats
optional
If requesting a rollup cycle then include one or more stats to be returned. Overrides any statistics in the streams parameter. Comma delimited list.
  • FIRST
  • LAST
  • MIN
  • MAX
  • AVG
  • SUM
  • MINOCCURRENCE
  • MAXOCCURRENCE
  • GAPCOUNT
  • NONGAPCOUNT
  • INTVLCOUNT
  • MILLISECCOUNT
  • NONGAPMILLISECCOUNT
flatten
optional
Set to true or false. If true, the component layer is flattened and the list of streams and statistics will be in the order they were requested.
requestTimeZoneId
optional
The time zone of the request. Mandatory if the cycle and numIntvls parameters are passed in and the cycle is not directly referencing a time zone.
numIntvls
optional
If numIntvls is passed in then the endDate will be derived using the  passed in cycle and startDate. If startDate is missing then it will be derived using numIntvls, cycle, and endDate.
items
optional A delimited list of stream values being requested in this format: "componentUid.streamUid.cycleUid.statistics+componentUid.streamUid.cycleUid". Ensure parameter is encoded properly. If the cycleUid is missing then the base cycle is assumed. Statistics are comma delimited. Statistics can be missing if only requesting last value information or base cycle intervals.
itemsById
optional A JSON array of stream values being requested by item ids (not uids). Each object in the array has this format:
[{"compId":"aComponentId","streamId":"aStreamId","cycleId":"aCycleId","stats":"AVG,SUM"}]

Ensure parameter is encoded properly. If the cycleUid is missing then the base cycle is assumed. Statistics are comma delimited. Statistics can be missing if only requesting last value information or base cycle intervals.
itemsByFolderPath
streamId
streamName
includeSubs
optional Set itemsByFolderPath to the absolute path (i.e. /wharehouse1). Leave off "Components". Set streamId to return only streams that match the ID (wildcard ID accepted). Set streamName to return only streams that match the name (wildcard names accepted). Setting streamId and streamName to nothing will cause the search to return all streams. Set includeSubs to to search all descendent folders. All four of these parameters are required within the same call.

Example Requests

Return the 5 minute average of 3 interval streams, each with 20 second base cycle intervals. Return 5 minute interval interval dates.

feed?startDate=1319053200000&endDate=1319054100000&items=c7782a07-d12b-45d1-845a-5ec2e2160696.7039044e-055f-40d5-b92c-5f2171434cd1.75ee104d-a73c-4633-88aa-476e46240d95%2Bc7782a07-d12b-45d1-845a-5ec2e2160696.3e82a87d-a5df-4e95-b961-9c2e0908bce1.75ee104d-a73c-4633-88aa-476e46240d95%2Bc7782a07-d12b-45d1-845a-5ec2e2160696.2e3c0ce3-af64-4ae2-a976-d9a97c2df2d6.75ee104d-a73c-4633-88aa-476e46240d95&intvlDates=return&stats=AVG


Response Body
{
  "message": "",
  "feed": {
    "requestStartDate": 1319053200000,
    "component": [
      {
        "stream": [
          {
            "statistic": [
              {
                "name": "AVG",
                "data": [
                  5.766666666666667,
                  5.32,
                  13.11111111111111
                ],
                "type": "DOUBLE"
              }
            ],
            "intvlStartDate": [
              1319053200000,
              1319053500000,
              1319053800000
            ],
            "completedDate": 1319054320000,
            "cycleUid": "75ee104d-a73c-4633-88aa-476e46240d95",
            "lastValueType": "FLOAT",
            "intvlEndDate": [
              1319053500000,
              1319053800000,
              1319054100000
            ],
            "streamType" : "intvl_stream",
            "streamUid": "7039044e-055f-40d5-b92c-5f2171434cd1",
            "lastUpdated": 1319054328307,
            "lastValue": 14.300000190734863
          },
          {
            "statistic": [
              {
                "name": "AVG",
                "data": [
                  1,
                  1.25,
                  3.98
                ],
                "type": "DOUBLE"
              }
            ],
            "intvlStartDate": [
              1319053200000,
              1319053500000,
              1319053800000
            ],
            "completedDate": 1319054320000,
            "cycleUid": "75ee104d-a73c-4633-88aa-476e46240d95",
            "lastValueType": "FLOAT",
            "intvlEndDate": [
              1319053500000,
              1319053800000,
              1319054100000
            ],
            "streamType" : "intvl_stream",
            "streamUid": "3e82a87d-a5df-4e95-b961-9c2e0908bce1",
            "lastUpdated": 1319054328319,
            "lastValue": 1
          },
          {
            "statistic": [
              {
                "name": "AVG",
                "data": [
                  92.83333333333333,
                  93.54,
                  83.07777777777778
                ],
                "type": "DOUBLE"
              }
            ],
            "intvlStartDate": [
              1319053200000,
              1319053500000,
              1319053800000
            ],
            "completedDate": 1319054320000,
            "cycleUid": "75ee104d-a73c-4633-88aa-476e46240d95",
            "lastValueType": "FLOAT",
            "intvlEndDate": [
              1319053500000,
              1319053800000,
              1319054100000
            ],
            "streamType" : "intvl_stream",
            "streamUid": "2e3c0ce3-af64-4ae2-a976-d9a97c2df2d6",
            "lastUpdated": 1319054328297,
            "lastValue": 84.30000305175781
          }
        ],
        "componentUid": "c7782a07-d12b-45d1-845a-5ec2e2160696"
      }
    ],
    "requestEndDate": 1319054100000
  },
  "success": true
}


Return the base cycle intervals of three interval Streams:

feed?startDate=1319054040000&endDate=1319054100000&items=c7782a07-d12b-45d1-845a-5ec2e2160696.7039044e-055f-40d5-b92c-5f2171434cd1.b2a4da07-5182-4b2e-a1d4-e092e75a82ec%2Bc7782a07-d12b-45d1-845a-5ec2e2160696.3e82a87d-a5df-4e95-b961-9c2e0908bce1.b2a4da07-5182-4b2e-a1d4-e092e75a82ec%2Bc7782a07-d12b-45d1-845a-5ec2e2160696.2e3c0ce3-af64-4ae2-a976-d9a97c2df2d6.b2a4da07-5182-4b2e-a1d4-e092e75a82ec&intvlDates=return

Response Body
{
  "message": "",
  "feed": {
    "requestStartDate": 1319054040000,
    "component": [
      {
        "stream": [
          {
            "statistic": [
              {
                "name": "BASE",
                "data": [
                  null,
                  28.100000381469727,
                  null
                ],
                "type": "FLOAT"
              }
            ],
            "intvlStartDate": [
              1319054040000,
              1319054060000,
              1319054080000
            ],
            "completedDate": 1319054760000,
            "cycleUid": "b2a4da07-5182-4b2e-a1d4-e092e75a82ec",
            "lastValueType": "FLOAT",
            "intvlEndDate": [
              1319054060000,
              1319054080000,
              1319054100000
            ],
                        "streamType" : "intvl_stream",
            "streamUid": "7039044e-055f-40d5-b92c-5f2171434cd1",
            "lastUpdated": 1319054748319,
            "lastValue": 20.5
          },
          {
            "statistic": [
              {
                "name": "BASE",
                "data": [
                  null,
                  6.900000095367432,
                  null
                ],
                "type": "FLOAT"
              }
            ],
            "intvlStartDate": [
              1319054040000,
              1319054060000,
              1319054080000
            ],
            "completedDate": 1319054760000,
            "cycleUid": "b2a4da07-5182-4b2e-a1d4-e092e75a82ec",
            "lastValueType": "FLOAT",
            "intvlEndDate": [
              1319054060000,
              1319054080000,
              1319054100000
            ],
                        "streamType" : "intvl_stream",
            "streamUid": "3e82a87d-a5df-4e95-b961-9c2e0908bce1",
            "lastUpdated": 1319054748330,
            "lastValue": 1.2000000476837158
          },
          {
            "statistic": [
              {
                "name": "BASE",
                "data": [
                  null,
                  64.4000015258789,
                  null
                ],
                "type": "FLOAT"
              }
            ],
            "intvlStartDate": [
              1319054040000,
              1319054060000,
              1319054080000
            ],
            "completedDate": 1319054760000,
            "cycleUid": "b2a4da07-5182-4b2e-a1d4-e092e75a82ec",
            "lastValueType": "FLOAT",
            "intvlEndDate": [
              1319054060000,
              1319054080000,
              1319054100000
            ],
                        "streamType" : "intvl_stream",
            "streamUid": "2e3c0ce3-af64-4ae2-a976-d9a97c2df2d6",
            "lastUpdated": 1319054748315,
            "lastValue": 77.9000015258789
          }
        ],
        "componentUid": "c7782a07-d12b-45d1-845a-5ec2e2160696"
      }
    ],
    "requestEndDate": 1319054100000
  },
  "success": true
}


Return a set of samples for one random stream (only one sample is returned):

http://localhost:8080/labrador-client/api/feed?org=00000000-0000-0000-0000-000000000001&startDate=1347893959477&endDate=1347893959478&intvlDates=return&flatten=true&items=f0254242-d7f5-3baf-8f41-99b18db6c101.2f636fe0-ed37-3961-8529-666ff72b26d3&_dc=1347900865033

Response Body
{
  "message": "",
  "feed": {
    "stream": [
      {
        "statistic": [
          {
            "name": "BASE",
            "data": [
              0.29
            ],
            "type": "DOUBLE"
          }
        ],
        "completedDate": 1347893959478,
        "time": [
          1347893959477
        ],
        "lastValueType": "DOUBLE",
        "streamUid": "2f636fe0-ed37-3961-8529-666ff72b26d3",
        "streamType": "rdm_stream",
        "componentUid": "f0254242-d7f5-3baf-8f41-99b18db6c101",
        "lastUpdated": 1347895759478,
        "lastValue": 0.29
      }
    ],
    "requestStartDate": 1347893959477,
    "requestEndDate": 1347893959478
  },
  "success": true
}

PUT feed (Batch - JSON Body)



Inserts or updates a range of intervals for a collection of component stream feeds. The PUT data is contained within the JSON body of the PUT. Multiple component feeds can be updated within one call.
 

There are two formats for feed intervals being uploaded:
1) The startDate is passed with an array of intervals. This is the first interval's start datetime. This only applies to interval streams.
2) An array of intervals, each with an interval start datetime (epoch millis). These values do not have to be sorted. Each datetime in the array will correspond to the value in the data array at the same index location. The data value will be inserted into the cycle interval that the time falls within (startDate inclusive, endDate exclusive). If more than one value falls within an interval then the last value is used. This method can be used for all stream types.

Each set of samples should be associated with a component and stream. This association can occur in several ways:
1) Component association
  • The most efficient way to identify which component the stream belongs to is to include the componentUid, but this is the most difficult technique to implement for a device and is rarely used.
  • The componentId. This is the easiest technique to implement for a device and is most often used.
  • Component templateId and componentId. This combination will allow a device to register itself automatically (create a component based on the template id if the component with the passed in componentId doesn't already exist) while uploading its feed. Some component attributes can be passed during this call. They will be assigned to the component in the initial registration call. This is not the most efficient way to upload feed data since extra data has to be passed and server side look-ups need to occur but it is the easiest technique for a device developer who wants to have their devices automatically register with GroveStreams
2) Stream association identifiers
  • The most efficient way to identify a stream is by including its uid in the feed
  • The streamId
  • The order the stream is in the component's stream array. The order of the stream within the feed will assume it matches the order of streams during a component PUT/POST (or the order as seen from within the user interface).

The following default component attributes can be set under the feed's component json object when the component is created during the feed insertion if a componentTemplateId and a componentId are included:
  • component.defaults.name, description, timeZoneId, dispostion
  • component.defaults.location.latitude, longitude, altitude, hasAltitude, description, street, city, stateOrProvince, postalCode, country

Automatically created components will be placed in the component_folder root location.

A Feed PUT will also dynamically create streams which may not exist within an existing component or template. Default metadata information for the dynamically created stream can be included in the stream. A random stream will be automatically created if no template or default metadata is included.

A feed PUT call will return a list of streams that are missing from a component during a feed PUT. This allows a device to not have to include stream metadata for every PUT upload for automatic stream creation. It can send the metadata when the server reports that the stream is missing. See the GroveStreams gs_gmetad code for an example of this technique.

The startDate and time attributes can be set at the feed, component or stream level. The highest level will be used during the insert.

Feed Put calls are limited to 2,000 streams per call. The number of samples per stream is only limited by the body size limit. Use gzip compression whenever possible.

Resource Information
Rate Limited?
Yes
session, oauth and org tokens compatible?
Yes
api_key token token compatible?
Yes



Resource URL

http://grovestreams.com/api/feed

Parameters

compTmplId
optional
The ID of a component template that will be used to auto-create a component for this feed if one does not already exist. The component ID will be used for the component name if one is not provided.
folder
optional
The folder to place a newly created component into. Must start with /Components. The folder will be created if one does not exist.
dtId
dsId
Optional
These parameters are used to dynamically create streams for a component if they do not exist based on a component template stream. The stream definition will be based on a component template stream definition. These parameters are useful for times when the default new stream is not what is desired. For example, a caller may require new streams to be interval streams or streams with units already defined. These parameters can accomplish this.
dtId: The ID of the component template that contains the stream to be used as the template for the new stream.
dsId: The ID of the stream within the component template to be used as the template for the new stream.
createDefault Optional
Defaults to true if missing. Tells GS to automatically create a new component if one with the passed in ID does not exist. It also tells GS to automatically create a new default stream if one does not exist. The stream will be a random stream and its value type will be either a String or Double depending on the sample passed in. If the sample can be converted to a Double, then the type will be Double. If it cannot be converted to a Double, then the type will be a String.
derMaxS optional
Defaults to 0 if missing. Defaults to 20 if exists but is not assigned a value. 20 is the maximum. derMaxS is the maximum number of precedent expression streams to derive during the Feed PUT. Derivation will happen within the same transaction as the Feed PUT (synchronously). A higher number of streams to derive will cause a longer Feed PUT time. Limit the derivation time by setting derMaxS to a smaller value or by setting derTout. All streams impacted by the Feed PUT streams will be derived while walking up the derivation dependency tree. Derivation will stop when derMaxS is reached. Derivation will stop working up a precedent branch if a component is locked by another process, derivation fails due to exceptions, derivation did not derive any new intervals. Derivation will only occur for Feed PUTs that are appending samples. Derivation also works for batch Feed PUTs.

This feature is used to execute derivation as data arrives by our web servers. Normal derivation still occurs within the Job framework on Job servers and will attempt to derive all streams that need deriving every few minutes.
derTout optional
Defaults to 0 if missing. Defaults to 15000 milliseconds if exists but is not assigned a value. 15000 is the maximum. derTout is the timeout amount, in milliseconds, for the entire Feed PUT call. It is used to ensure that derivation will not increase the Feed PUT total time too much. For example, assume we want a maximum time of 2000ms (or 2 seconds) to make a Feed PUT call. If the saving of the stream samples during a Feed PUT takes 500ms we would then set derTout to 2000ms to allow for derivation to take a maximum time of 1500ms.

If saving the stream samples takes 1000ms and derTout is set to 500ms, the stream data will still be saved but derivation will not happen. Setting derTout to anything will not impact the saving of stream data.

Example Requests

Upload 10 intervals of data for one stream (each interval is one second so ten seconds worth of data is being uploaded). To upload more streams in the same call,  add them to the appropriate json branch. Each component has its own space in the component array, each set of stream intervals have their own space in the stream array.

This example demonstrates how a device knows the componentUid and streamUid for each stream. This is the optimal way of uploading feeds.

Whenever possible, during device start-up or registration, a device should make a GET component call to GroveStreams using its unique device Id to get its uid and its stream uids so that they can be used for uploading feeds efficiently.

Note that the startDate attribute could be at the feed, component or stream level. The below example has it set at the component level for an interval stream feed.

/feed


Request Body
{
  "feed": {
    "component": [
      {
        "startDate": 1316782980000,
        "componentUid": "59d9d98d-bd17-4b7c-a99a-77b49fbad29b",
        "stream": [
          {
            "streamUid": "f5f54ceb-47c6-4c4b-baa2-34eb82238f52",
            "data": [
              6.965172290802002,
              5.276381969451904,
              6.483793258666992,
              6.6997528076171875,
              10.447758436203003,
              12.594455480575562,
              19.900494813919067,
              9.068012237548828,
              8.977556228637695,
              13.681590557098389
            ]
          }
        ]
      }
    ]
  }
}



This next example demonstrates a device uploading three interval stream feeds by using the component id (not uid) and the order of the streams to identify what data belongs to which streams.

/feed


Request Body

{
  "feed": {
    "startDate": 1293840000000,
    "component": [
      {
        "stream": [
          {
            "data": [
              "A sample data string1",
              "A sample data string2",
              "A sample data string3"
            ]
          },
          {
            "data": [
              3,
              6,
              8
            ]
          },
          {
            "data": [
              3.140000104904175,
              9.220000267028809,
              5.760000228881836
            ]
          }
        ],
        "componentId": "MAC4563454"
      }
    ]
  }
}


This next example demonstrates setting the startDate at the stream level.

/feed


Request Body
{
  "feed": {
    "component": [
      {
        "stream": [
          {
            "startDate": 1293840000000,
            "streamUid": "e4219421-e92c-4f54-84c4-e97b763eb4bb",
            "data": [
              "A sample data string1",
              "A sample data string2",
              "A sample data string3"
            ]
          },
          {
            "startDate": 1293840000000,
            "streamUid": "37c6bda7-fa05-468e-ad10-98344b66ddc1",
            "data": [
              3,
              6,
              8
            ]
          },
          {
            "startDate": 1293840000000,
            "streamUid": "12654565-82c3-4e0a-aa4a-8e4e342d3428",
            "data": [
              3.140000104904175,
              9.220000267028809,
              5.760000228881836
            ]
          }
        ],
        "componentUid": "d4229767-03ae-4e05-8919-e5b144524267"
      }
    ]
  }
}



This next example demonstrates automatic creation of a component, if it doesn't already exist, with a component template and setting some of the new component attributes.

/feed


Request Body
{
  "feed": {
    "startDate": 1293840000000,
    "component": [
      {
        "componentTemplateId": "template1",
        "stream": [
          {
            "streamId": "id3",
            "data": [
              "A sample data string1",
              "A sample data string2",
              "A sample data string3"
            ]
          },
          {
            "streamId": "Stream2",
            "data": [
              3,
              6,
              8
            ]
          },
          {
            "streamId": "Stream3",
            "data": [
              3.140000104904175,
              9.220000267028809,
              5.760000228881836
            ]
          }
        ],
        "defaults": {
          "location": {
            "stateOrProvince": "NJ"
          },
          "name": "smart plug",
          "folderPath" : "/home/kitchen"
        },
        "componentId": "MAC4563454"
      }
    ]
  }
}


This next example demonstrates using the time attribute with values that are unordered and that do not fall exactly on the interval start datetime (note that the time attribute can exist at the feed, component or stream level). Using the time technique allows this feed to be used for all three stream types: interval, random and point

/feed


Request Body
{
  "feed": {
    "component": [
      {
        "stream": [
          {
            "time": [
              1293840001001,
              1293840000999,
              1293840002000
            ],
            "streamUid": "a2702ddb-91a3-4cf2-a3d4-f0bf5ecc87fe",
            "data": [
              "A sample data string2",
              "A sample data string1",
              "A sample data string3"
            ]
          },
          {
            "time": [
              1293840001001,
              1293840000999,
              1293840002000
            ],
            "streamUid": "810703fa-bbde-4ca8-b26c-a7e80909011f",
            "data": [
              6,
              3,
              8
            ]
          },
          {
            "time": [
              1293840001001,
              1293840000999,
              1293840002000
            ],
            "streamUid": "5f72261f-cfa3-4cfc-9b8e-56abb6937bf8",
            "data": [
              9.220000267028809,
              3.140000104904175,
              5.760000228881836
            ]
          }
        ],
        "componentUid": "56e56a08-532b-4a53-a659-e327577f2d89"
      }
    ]
  }
}


This next example demonstrates automatically creating a component and streams if they do not already exist. It relies on component templates, units, cycles and rollup calendars existing within the organization with ids that match the ones in the feed. Note that this example is from our Ganglia computer resource monitoring feeder which has all the dependent resources (templates, units, cycles, rollup calendars) automatically created by importing the Ganglia template.

Adding all this metadata will increase the transaction size. Feeders should be built to only upload metadata periodically so as to keep transaction costs low. The GroveStreams server will return a list of streamIds that are missing for each component-stream feed being uploaded. The caller should monitor the missing list and only upload the metadata when it is needed to create a stream.

/feed


Request Body
{
  "feed": {
    "component": [
      {
        "componentTemplateId": "gs.ganglia",
        "defaults": {
          "location": {
            "description": "unspecified"
          },
          "name": "Production - localhost.localdomain"
        },
        "componentId": "127.0.0.1",
        "stream": [
          {
            "defaults": {
              "streamType": "intvl_stream",
              "baseCycleId": "gs.20sec",
              "description": "Total number of processes",
              "name": "process: Total Processes",
              "valueType": "INTEGER",
              "rollupCalendarId": "standard",
              "gap_filling": {
                "maxGapsToFill": 20,
                "gapFillType": "PREVIOUS_VAL"
              },
              "comp_group": {
                "id": "sysInfo",
                "name": "System Information"
              },
              "unitId": "noSymbol"
            },
            "time": [
              1343311858680
            ],
            "streamId": "proc_total",
            "data": [
              "852"
            ]
          },
          {
            "defaults": {
              "streamType": "intvl_stream",
              "baseCycleId": "min",
              "description": "Packets out per second",
              "name": "network: Packets Sent",
              "valueType": "FLOAT",
              "rollupCalendarId": "standard",
              "gap_filling": {
                "maxGapsToFill": 20,
                "gapFillType": "PREVIOUS_VAL"
              },
              "unitId": "gs.packetsPerSecond"
            },
            "time": [
              1343311858680
            ],
            "streamId": "pkts_out",
            "data": [
              "3.70"
            ]
          }
        ]
      }
    ]
  }
}

DELETE feed



Deletes a range of intervals for all streams specified. This only applies to interval and random streams.

The range can be any range even if it falls outside the range of existing interval data. No errors will be returned even if this occurs.
Resource Information
Rate Limited?
Yes
session, oauth and org tokens compatible?
Yes
api_key token compatible
Yes



Resource URL

http://grovestreams.com/api/feed

Parameters

startDate
optional
The start datetime (epoch millis) of the range request. GroveStreams will round to the start of the interval it falls within. Requires startDate.
endDate
optional
The end datetime (epoch mills) of the range request. GroveStreams will round to the end of the interval it falls within. Requires endDate.
streams
mandatory
A delimited list of streams in this format: "componentUid.streamUid+componentUid.streamUid". Ensure argument is encoded properly.

If both startDate and endDate parameters are missing then all intervals will be deleted.

Example Requests

Deletes a range of intervals from one stream.

/feed?startDate=1316781300000&endDate=1316781360000&streams=59d9d98d-bd17-4b7c-a99a-77b49fbad29b.f5f54ceb-47c6-4c4b-baa2-34eb82238f52%2B59d9d98d-bd17-4b7c-a99a-77b49fbad29b

Response Body
{
  "message": "",
  "success": true
}