HTTP API Resources

The below API is a simple API based on REST. See the GroveStreams Advanced API for more advanced calls.

Resource	Description

Feeds
PUT feed (no JSON body)	Updates or inserts a set of samples for one component. This call involves no JSON.
PUT feed	Updates or Inserts a set of feed samples for one or more components. Uses JSON.
GET comp/{compId}/feed	Returns a list of feed samples for each of a component's streams.
GET comp/{compId}/stream/{streamId}/feed	Returns a list of feed samples for one component stream.
GET comp/{compId}/last_value	Returns the last sample for each of a component's streams.
GET comp/{compId}/stream/{streamId}/last_value	Returns the last sample for one component stream.
GET comp/{compId}/cycle/{cycleId}/stat/{statId}/feed	Returns a list of statistic feed samples for each of a component's streams.
GET comp/{compId}/stream/{streamId}/cycle/{cycleId}/stat/{statId}/feed	Returns a list of statistic feed samples for one component stream.
GET comp/{compId}/cycle/{cycleId}/stat/{statId}/last_value	Returns the last statistic sample for each of a component's streams.
GET comp/{compId}/stream/{streamId}/cycle/{cycleId}/stat/{statId}/last_value	Returns the last statistic sample for one component stream.
GET comp/{compId}/property	Returns a component property such as its name.
POST comp/{compId}/property	Sets a component property such as its name.
PUT comp/{compId}/stream/{streamId}/feed/file/{fileName}	Inserts or updates a file into a file stream.
GET comp/{compId}/stream/{streamId}/feed/file/{time}/{fileName}	Gets a file from a file stream.
GET comp/{compId}/stream/{streamId}/feed/file/{fileName}	Gets a file from a file stream.

Two important reminders:

1) Always include the api_key parameter as part of the request URL or as a cookie. Most of the examples below do not include this parameter to make them easier to read. Select the API Keys button to manage your API keys and select View Secret Key to get your api_key parameter.
2) URLs must have special characters encoded. Your component, stream or cycle IDs will need to be URL encoded if they include reserved characters such as spaces or commas. There are many free URL encoders on-line that you can use to encode your URL such as freeformatter.com.

This API relies on component, stream, and cycle IDs. GroveStreams allows these IDs to be optionally blank. Edit your components, streams, and cycles within the GroveStreams studios and add IDs to each of these entity instances if you would like to use this API.

PUT feed (No JSON Body)

Inserts samples for a single component's set of streams. All identifiers and data are part of the URL. There is no JSON body passed with the PUT. This call is useful for situations where there is only one device with many feeds being uploaded such as Arduino boards with many sensors since assembling JSON can be resource intensive and complex. A GroveStreams server will calculate the sample time(s) if no time stamp(s) are passed in. A default component and Random streams will be automatically created if they do not exist. Use the compTmplId and/or the dtId/dsId parameters to override the defaults. Ensure the earliest times are listed first when passing in a set of delimited values and times. Ensure the delimited sample times are in the same order as the delimited sample values. Ensure the api_key token is part of the URL or is passed in as a cookie. Note that this is a PUT call. Copying and pasting your URL into a browser will not work as the browser will use a GET http command instead of a PUT. Ensure reserved characters, such as commas, are URL encoded (commas should be encoded as %2C)	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

compId	mandatory	The ID of the Component that contains the streams for the new samples. The compId value will be assigned to a the new component if the compTmplId parameter is included.
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.
compName	optional	The name to assign to a new component that is created from the compTmplId. The name is only set once during the creation of the component.
time timeEl freq	optional	None or only one of these parameters can be part of the URL. They are used to determine the time stamp of each sample. Pass in none of these parameters, if only one sample per stream is being uploaded, and the GroveStreams servers will automatically assign a time. time: A delimited set of sample times, one for each sample set. In epoch millis. The delimited order must match the order of the data or stream ID parameters. timeEl: A delimited set of milliseconds that has elapsed since each sample reading. A GroveStreams server will use the elapsed times along with the current time of the upload to determine the actual time stamp. The delimited order must match the order of the data or stream ID parameters. freq: A single number (not a delimited set of numbers). The freq is the frequency, in milliseconds, that the samples were taken in. A GroveStreams server will use the freq to determine the actual time stamp of each sample using the current time of the upload. Ensure the delimited data values are listed earliest first.
data	optional*	The sample data values. The URL can have many 'data' parameters; one for each component stream. The order they appear in the URL must match the order of the streams within the component definition. Each data parameter can contain many samples for a single stream. Each value should be delimited by a comma. The earliest sample should be first. You must also include a time, timeEl, or freq parameter if a delimited set of data values are passed in. The URL must have a 'data' parameter or stream id parameters.
stream id parameters	optional*	Use each stream ID for sample assignment. For example, if there are two streams with IDs, temp and wind, then they can be assigned like this: &temp=10.5&wind=15.1 Each stream id parameter can contain many samples for a single stream. Each value should be delimited by a comma. The earliest sample should be first. You must also include a time, timeEl, or freq parameter if a delimited set is passed in. The URL must have a 'data' parameter or stream id parameters.
rsid	optional*	Request stream IDs. A stream's last_value will be returned for each 'rsid' included in the URL. The return result will be part of the http response body formatted as JSON (see below for examples). The requested streams must belong to the same component that the Feed PUT is updating. Request streams are useful for devices that need to bring back information from GroveStreams for use on the device. A device may need to retrieve a value that is needed for a local calculation, but the most likely use case is for a device to monitor for commands or property changes. Control commands may be stored as stream values under the same component and retrieved with every Feed PUT call. This technique is firewall friendly and it prevents a device from constantly polling for new commands while keeping transaction counts low. The API key used with the call requires the capability for a Feed GET when an rsid parameter is included. It's settings should look like this: component/*/feed GET PUT
delim	optional*	The delimiter used within each data, stream id, time, and timeEl to separate sample times and sample data values. It will be assumed that a comma "," is the delimiter if the delim parameter is not part of the URL. Note that URL special characters need to be encoded - for example, the comma needs to appear as "%2C" within the url.
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.
asPut	optional	Some gateways only support HTTP GET methods. Including this parameter on the URL will cause GroveStreams to process a feed GET as a PUT. For example, this call: GET http://grovestreams.com/api/feed?compId=comp1&data=3&data=4&asPut will be processed by our PUT logic including verifying the api_key has the proper rights for a PUT feed call.
autofillGapsWithNulls	optional	Defaults to true. This parameter is only used if uploading into an interval stream and the samples being uploaded are missing interval sample times within the timespan being uploaded. When true, Nulls are inserted and overwrite the values in the store for the missing interval times in the upload. Setting this parameter to false will preserve the store values for the missing uploaded samples.
derMaxS	optional	Defaults to 0 if missing. Defaults to 20 if exists but is not assigned a value. 20 is the maximum. derMaxS is 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 any components are 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 will work for batch Feed PUTs too. 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 PUT Requests - One Sample Per Stream

All calls must include the api_key token.

Upload Two Stream Samples

Let GroveStreams set the time of the samples.
The streams are determined by their order within the component model definition.
A component with an ID of comp1 must exist.

Request URL:

http://grovestreams.com/api/feed?compId=comp1&data=3&data=4

Upload Two Stream Samples

Let GroveStreams set the time of the samples.
The streams are determined by their order within the component model definition.
Include a component template id so that the component will be auto-created based on a template if it is missing:

Request URL:

http://grovestreams.com/api/feed?compTmplId=compTmpl1&compId=comp1&data=1&data=2

Upload Two Stream Samples

Let GroveStreams set the time of the samples.
The streams are determined by their order within the component model definition.
Auto-create the component if it is missing based on the component template Id.
Assign the new component the name 'Weather'.

Request URL:

http://grovestreams.com/api/feed?compTmplId=compTmpl1&compId=comp1&compName=Weather&data=1&data=2

Upload Three Stream Samples

Let GroveStreams set the time of the samples.
A component with an ID of comp1 must exist.
Explicitly assign the values to specific streams by using the stream IDs (temp, wind, winddir).

Request URL:

http://grovestreams.com/api/feed?compId=comp1&temp=3&wind=4&winddir=sw

Include the Time of the Samples

The time for all samples is passed in as epoch millis.
A component with an ID of comp1 must exist.
Explicitly assign the values to specific streams by using the stream IDs (temp, wind, winddir).

Request URL:

http://grovestreams.com/api/feed?time=1380114721384&compId=comp1&temp=3&wind=4&winddir=sw

Upload Samples with Request Streams

The rsid parameter is included so that the last_value of each rsid stream is returned within the same Feed PUT call. This call is requesting the sleep and awake times, in milliseconds, for a sensor that sleeps to conserve power. The sensor may adjust these settings if they have changed.

Request URL:

http://grovestreams.com/api/feed?;compId=comp1&temp=3&wind=4&winddir=sw&rsid=sleep_time&rsid=awake_time

Response Body (never assume the order of the streams in the JSON will be the same):

{"sleep_time":600000,"awake_time":5000}

Response Body (awake_time stream has no samples saved in GroveStreams - null is returned for its last_value):

{"sleep_time":600000,"awake_time":null}

Response Body (Stream winddir was missing from the component and was auto created with this call. A "missing" json object will be included in the response along with the request streams.):

{"missing":[{"itemType":"stream","itemId":"winddir","componentId":"comp1"}],"sleep_time":600000,"awake_time":5000}

Example of Full URL With the api_key Token:

Request URL:

http://grovestreams.com:80/api/feed?time=1380114721384&compId=comp1&temp=3&wind=4&winddir=sw&api_key=0ccc2159-2697-3dcd-a211-588e9ccbed71

Example PUT Requests - Many Samples Per Stream

Upload Two Samples for Each Stream

A component with an ID of comp1 must exist.
The streams are determined by their order within the component model definition.
Pass in two sets of samples for each stream and include the time of each sample as epoch millis.

Request URL:

http://grovestreams.com:80/api/feed?compId=comp1&time=1380225121172,1380225181172&data=3,4&data=4,6

Upload Two Samples for Each Stream

Auto-create the component if it is missing based on the component template Id.
Assign the new component the name 'Weather'.
Pass in more than one set of samples and include the freq parameter to let GroveStreams calculate the sample times with the current time and a frequency of 60 seconds between sample reads. The earliest sample must be listed first in each data delimited set.

Request URL:

http://grovestreams.com:80/api/feed?compTmplId=compTmpl1&compId=comp1&compName=Weather&freq=60000&data=1,2&data=3.0,4.0

Upload Two Samples for Each Stream

Auto-create the component if it is missing based on the component template Id.
Assign the new component the name 'Weather'.
Explicitly assign the values to specific streams by using the stream IDs (temp, wind, winddir).
Pass in more than one set of samples and include a set of time elapsed values since the samples were taken in milliseconds.

Request URL:

http://grovestreams.com:80/api/feed?compTmplId=compTmpl1&compId=comp1&compName=Weather&timeEl=60000,0&temp=3,4&wind=4.0,5.5&winddir=sw,sw

Example of Full URL With the api_key Token

Request URL:

http://grovestreams.com:80/api/feed?compTmplId=compTmpl1&compId=comp1&compName=Weather&timeEl=60000,0&temp=3,4&wind=4.0,5.5&winddir=sw,sw&api_key=0ccc2159-2697-3dcd-a211-588e9ccbed71

PUT feed

Accepts an array of samples to be inserted or updated. Samples can be from one or more components and streams. This call will auto-create a component if it does not exist. It will also auto-create streams, as random streams, if they do not exist. The new component name and ID will be the compId value passed in and it will be set with the organization owner's time zone. Auto-created streams will be Random Streams with a value type of either DOUBLE or STRING depending on the initial data being uploaded. Use the compTmplId and/or the dtId/dsId parameters to override the new component and stream defaults. A GroveStreams server will assign a sample time if one is not included.	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.
autofillGapsWithNulls	optional	Defaults to true. This parameter is only used if uploading into an interval stream and the samples being uploaded are missing interval sample times within the timespan being uploaded. When true, Nulls are inserted and overwrite the values in the store for the missing interval times in the upload. Setting this parameter to false will preserve the store values for the missing uploaded samples.
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 will work for batch Feed PUTs too. 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 PUT Request

All calls must include the api_key token.

Upload Several Stream Samples for Two Components

This example will upload two samples for a component with an ID of 'comp1' and it will upload three samples for a component with an ID of 'comp2'.
The 'comp1' sample times will be set by the GroveStreams servers.
The 'comp2' sample times are passed in with each of its samples (as epoch millis).
Streams are identified by including the mandatory 'streamId' attribute for each sample (wind, temp, speed, heading, status).

Request URL:

http://grovestreams.com/api/feed

Request Body:

[
  {
    "compId": "comp1",
    "streamId": "wind",
    "data": 2.34
  },
  {
    "compId": "comp1",
    "streamId": "temp",
    "data": 72.3
  },
  {
    "compId": "comp2",
    "streamId": "speed",
    "data": 20
  },
  {
    "compId": "comp2",
    "streamId": "heading",
    "data": 120.2,
    "time": 1380225121172
  },
  {
    "compId": "comp2",
    "streamId": "status",
    "data": "normal",
    "time": 1380225121172
  }
]

Example of Full URL With the api_key Token

http://grovestreams.com:80/api/feed?compTmplId=compTmpl1&api_key=0ccc2159-2697-3dcd-a211-588e9ccbed71

GET comp/{compId}/ :

comp/{compId}/feed

comp/{compId}/stream/{streamId}/feed

comp/{compId}/last_value

comp/{compId}/stream/{streamId}/last_value

comp/{compId}/cycle/{cycleId}/stat/{statId}/feed

comp/{compId}/stream/{streamId}/cycle/{cycleId}/stat/{statId}/feed

comp/{compId}/cycle/{cycleId}/stat/{statId}/last_value

comp/{compId}/stream/{streamId}/cycle/{cycleId}/stat/{statId}/last_value

All of these calls accept the same parameters and return the same result format which is an array of JSON objects that represent a collection of samples. Calls that return samples for more than one stream will be ordered by the order the stream appears within the component followed by the order of the sample time, latest to earliest. Only one Point stream sample will be returned for queries that request Point stream samples. Its time will be the time it was last updated. The time for interval streams is the end datetime of the sample interval. All cycle stat calls return interval stream samples. Statistic IDs (used for stat calls): first, last, min, max, avg, sum, minoccurrence, maxoccurrence, gapcount, nongapcount, intvlcount, milliseccount, nongapmilliseccount	Resource Information
	Rate Limited?	No
	session, oauth and org tokens compatible?	Yes
	api_key token token compatible?	Yes

API Key Definition:

Each of these calls is considered a component feed call. An api_key can be created with these settings to allow feeds for all components to be retrieved:
Resource: component/*/feed GET

Add the component UID in place of the * to restrict the key to a specific component instance. Add an IP address to the key definition to restrict the key to be used from a specific computer or device.

Resource URL

http://grovestreams.com/api/comp/{compId}/...

Parameters

sd	optional	Starting datetime (epoch millis). Inclusive. Must be used with ed parameter.
ed	optional	Ending datetime (epoch millis). Exclusive. The latest samples will be returned if this parameter is missing.
limit	optional	Used to restrict the number of items to return. 1,000 is the maximum. 1,000 is the default if this parameter is missing. Limit is from the latest samples back, starting with the first stream requested.
retFData	optional	Also return the data value formatted with its unit (fData).
retUnit	optional	Also return the data unit (unit).
retStreamId	optional	Also return the stream ID (streamId).
retCompId	optional	Also return the component ID (compId).
retIntvlSd	optional	Also return each interval stream's interval start time (sdTime).

Example GET Requests

All calls must include the api_key token.

Get the Latest Component's Stream's Samples

This example will return 1,000 samples for all of the streams that belong to the component with an ID of 'comp1'. The Stream ID is requested to be included with each sample per the inclusion of the retStreamID URL parameter.

Request URL:

http://grovestreams.com/api/comp/comp1/feed?retStreamId

Response Body:

[
 {
    "streamId": "wind",
    "data": 2.34,
    "time": 1380225121000
 },
 {
    "streamId": "wind",
    "data": 2.34,
    "time": 1380225122000
 },
 {
    "streamId": "temp",
    "data": 72.3,
    "time": 1380225121000
 },
 {
    "streamId": "temp",
    "data": 72.3,
    "time": 1380225122000
 },
	.... (996 samples not displayed for brevity)
]

Get the Latest Component's Stream's Samples for a Specific Range

This example will return all samples for all of the streams that belong to the component with an ID of 'comp1' that fall within the passed in start date (sd - inclusive) and end date (ed - exclusive). The Stream ID is requested to be included with each sample per the inclusion of the retStreamID URL parameter.

Request URL:

http://grovestreams.com/api/comp/comp1/feed?sd=1380225121000&ed=1380225122001&retStreamId

Response Body:

[
 {
    "streamId": "wind",
    "data": 2.34,
    "time": 1380225121000
 },
 {
    "streamId": "wind",
    "data": 2.34,
    "time": 1380225122000
 },
 {
    "streamId": "temp",
    "data": 72.3,
    "time": 1380225121000
 },
 {
    "streamId": "temp",
    "data": 72.3,
    "time": 1380225122000
 } 
]

Get the Latest Samples for One Component Stream

This example will return the last 4 samples for the 'wind' stream for the component with an ID of 'comp1'.

Request URL:

http://grovestreams.com/api/comp/comp1/stream/wind/feed?limit=4

Response Body:

[
 {
    "data": 2.34,
    "time": 1380225129000
 },
 {
    "data": 2.33,
    "time": 1380225128000
 },
 {
    "data": 2.30,
    "time": 1380225127000
 },
 {
    "data": 2.35,
    "time": 1380225126000
 } 
]

Get the Last Samples for Each of a Component's Streams

This example will return the last samples for all of the streams that belong to the component with an ID of 'comp1'. The Stream ID is requested to be included with each sample per the inclusion of the retStreamID URL parameter.

Request URL:

http://grovestreams.com/api/comp/comp1/last_value?retStreamId

Response Body:

[
 {
    "streamId": "wind",
    "data": 2.34,
    "time": 1380225121000
 },
 {
    "streamId": "temp",
    "data": 72.34,
    "time": 1380225122000
 },
 {
    "streamId": "status",
    "data": "active",
    "time": 1380225121000
 },
 {
    "streamId": "humidity",
    "data": 0.15,
    "time": 1380225122000
 } 
]

Get the Last Sample of One Component Stream

This example will return the last sample for the stream with ID 'wind' that belong to the component with an ID of 'comp1'.

Request URL:

http://grovestreams.com/api/comp/comp1/stream/wind/last_value

Response Body:

[
 {
    "data": 2.34,
    "time": 1380225121000
 }
]

Get the Latest Component's Stream's Statistic Samples

This URL will return the last 1,000 intervals for all of the streams that belong to the component with an ID of 'comp1'. Each interval will represent an hour and will contain the 'first' sample that fell within the statistic cycle 'hour'.

Request URL:

http://grovestreams.com/api/comp/comp1/cycle/hour/stat/first/feed

Get the Latest Statistic Values for One Component Stream

This URL will return the number of gaps for each 'month' for the 'wind' stream that belongs to the component with an ID of 'comp1'.

Request URL:

http://grovestreams.com/api/comp/comp1/stream/wind/cycle/month/stat/gapcount/feed

Get the Statistic Values for Each of a Component's Streams

This URL will return the times that the 'maximum' value occurred for each 'day' for each component stream.

Request URL:

http://grovestreams.com/api/comp/comp1/cycle/day/stat/maxoccurrence/last_value

Get the Last Statistic Value for One Component Stream

This URL will return the 'average' for the last 'hour' the last sample was uploaded within for a specific component stream. Cycle statistics may change as the samples they are calculated from are inserted or updated.

Request URL:

http://grovestreams.com/api/comp/comp1/stream/wind/cycle/hour/stat/avg/last_value

Get the Last Statistic Value for One Component Stream

This URL is like the one above but requests extra return attributes.

Request URL:

http://grovestreams.com/api/comp/comp1/stream/wind/cycle/hour/stat/avg/last_value?retFData&retUnit&retStreamId&retCompId&retIntvlSd

Response Body:

[
 {
    "compId": "comp1",
    "streamId": "wind",
    "data": 2.34,
    "time": 1380225121000,
    "fData": "2.3 mph",
    "unit": "mph",
    "sdTime": 1380225120000
 }
]

GET comp/{compId}/property

Returns one or more component properties such as the component's name.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token token compatible?	Yes

Resource URL

http://grovestreams.com/api/comp/{compId}/property

Parameters

name	optional	Include this URL parameter to return the component's name.
description	optional	Include this URL parameter to return the component's description.

Examples

All calls must include the api_key token.

Get a component's name

Request URL:

http://grovestreams.com/api/comp/front_door/property?name

Response Body:

[{
  "message": "",
  "component": {
    "name": "Front Door"
  },
  "success": true
}]

Get a component's description

Request URL:

http://grovestreams.com/api/comp/front_door/property?description

Response Body:

[{
  "message": "",
  "component": {
    "description": "The main entry door sensor which detects the state of the door such as open or closed."
  },
  "success": true
}]

Get a component's name and description

Request URL:

http://grovestreams.com/api/comp/front_door/property?description&name

Response Body:

[{
  "message": "",
  "component": {
    "name": "Front Door",
    "description": "The main entry door sensor which detects the state of the door such as open or closed."
  },
  "success": true
}]

POST comp/{compId}/property

Sets one or more component properties such as its name and description.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token token compatible?	Yes

Resource URL

http://grovestreams.com/api/comp/{compId}/property

Example PUT Request

All calls must include the api_key token.

Set a component's name

Request URL:

http://grovestreams.com/api/comp/front_door/property

Request Body:

[{

  "component": {
    "name": "Back Door"
  }
}]

Set a component's description

Request URL:

http://grovestreams.com/api/comp/front_door/property

Request Body:

[{

  "component": {
    "description": "This sensor was previously used for the front door."
  }
}]

Set a component's name and description

Request URL:

http://grovestreams.com/api/comp/front_door/property

Request Body:

[{

  "component": {
    "name": "Back Door",
    "description": "This sensor was previously used for the front door."
  }
}]

PUT comp/{compId}/stream/{streamId}/feed/file/{fileName}

Inserts or replaces a file for a single component file stream. The component and stream identifiers are part of the URL. There is no JSON body passed with the PUT. The file is sent as form-data. A GroveStreams server will use the current time if one is not passed in as a URL argument. A default component with a regular stream will be automatically created if it does not exist. Use the compTmplId and/or the dtId/dsId parameters to override the defaults. Ensure the api_key token is part of the URL or is passed in as a cookie. Reserved characters, such as commas and spaces, are to be URL encoded (commas should be encoded as %2C).	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token token compatible?	Yes

Resource URL

http://grovestreams.com/api/comp/{compId}/stream/{streamId}/feed/file/{fileName}

Parameters

compId	mandatory	The ID of the Component that contains the stream for the file being uploaded. The compId value will be assigned to a the new component if the compTmplId parameter is included.
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.
compName	optional	The name to assign to a new component that is created from the compTmplId. The name is only set once during the creation of the component.
streamId	mandatory	The stream ID for sample assignment.
time	optional	The time of the sample in epoch millis. The current time will be used if the time argument is missing.
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.

Examples

Java

See the Java - Quick Start tutorial for an example of how to upload a file into a stream.

Curl


					curl -F ‘file=@/home/gs/Pictures/GS_logo.jpg  http://grovestreams.com/api/comp/myCompId1/stream/mySreamID/feed/file?api_key=bd81d152-7101-327a-aaa4-eae5017dc26e

GET comp/{compId}/stream/{streamId}/feed/file/{time}/{fileName} :

comp/{compId}/stream/{streamId}/feed/file/{fileName}

comp/{compId}/stream/{streamId}/feed/file/{time}/{fileName}

These two calls accept the same parameters and return a file. Ensure the URL is properly encoded if the streamId or compId contain reserved URL characters such as spaces and commas. The time is in epoch Long format. Point streams are not supported for files as of today. The latest file for the stream will be returned if {time} is left off of the URL. Use the GET Feed calls to return lists of times and URLs that point to files that belong in component and streams.	Resource Information
	Rate Limited?	No
	session, oauth and org tokens compatible?	Yes
	api_key token token compatible?	Yes

API Key Definition:

Resource URL

http://grovestreams.com/api/comp/{compId}/stream/{streamId}/feed/file/{time}/{fileName}

Parameters

disposition	optional	Sets the response header Content-Disposition to this value. The HTTP request Content-Disposition can optionally be set instead. Defaults to inline if the request Content-Disposition type is not set or the disposition argument is missing. Values are inline (default value, indicating it can be displayed inside the Web page, or as the Web page) or attachment (indicating it should be downloaded; most browsers presenting a 'Save as' dialog, prefilled with the value of the filename parameters if present). A browser will usually download the file if it cannot display a file as inline. Installing a browser Add-In that allows the file to be displayed, such as a .pdf viewer, may allow the file to be viewed inline.
start	optional	Include the start parameter to return the file as a base64 string. The start parameter can be used to return the file back in chunks. Set the start parameter to the starting byte of the file to return.
limit	optional	Used with the start parameter. Set the limit parameter to the number of bytes to return. The number of bytes returned are the actual number of file bytes before converting to base64 and returning. Each chunk may be padded with pad characters at the end. Decoding each chunk usually removes those pads. Therefore, decode each chunk as it is returned instead of decoding it all at one time after all chunks have been returned. Nothing will be returned if start is attempting to access past the end of the file. The entire file will be returned, as a base64 string, if start is included in the URL and limit is not used in the URL.

Examples

GET a file for a specific time as "inline"

http://grovestreams.com/api/comp/myCompId1/stream/mySreamID/feed/file/1380114721384/GS_logo.jpg?api_key=bd81d152-7101-327a-aaa4-eae5017dc26e

GET the latest file as "inline"

http://grovestreams.com/api/comp/myCompId1/stream/mySreamID/feed/file/GS_logo.jpg?api_key=bd81d152-7101-327a-aaa4-eae5017dc26e

GET the latest file as "attachment" (or force download in a browser)

http://grovestreams.com/api/comp/myCompId1/stream/mySreamID/feed/file/GS_logo.jpg?api_key=bd81d152-7101-327a-aaa4-eae5017dc26e&disposition=attachment

GET the latest file as a base64 string in one call

http://grovestreams.com/api/comp/myCompId1/stream/mySreamID/feed/file/GS_logo.jpg?start=0&api_key=bd81d152-7101-327a-aaa4-eae5017dc26e

GET the latest file as a base64 string. Only get the first 200 bytes of the file

http://grovestreams.com/api/comp/myCompId1/stream/mySreamID/feed/file/GS_logo.jpg?start=0&limit200&api_key=bd81d152-7101-327a-aaa4-eae5017dc26e