REST HTTP API Conventions

What is RESTful?

A RESTful API is an application programming interface (API or web API) that conforms to the constraints of the REST architectural style and allows for interaction with RESTful web services.

Security

Tokens
A GroveStreams HTTP API token is an security identifier that is passed with an API call as a query string parameter or as a cookie. When passed as both a parameter and a cookie, GroveStreams will use the parameter token.

Tokens:

org
- This is the uid of the organization the API call is for. All organization calls need this token only if the session token is used. api_key calls do not require the org token as the org is inferred based on the organization the api_key resides within.
session
- The session token is created during the POST login or POST login_guest resource calls. The user credentials passed to the login resource will be associated with the session uid to determine access rights for each API call. Session tokens will expire during long time periods between API calls.
api_key
- The api_key token is used for cases where a user email and password should not be hard-coded or stored in a file. Api_keys should be used inside devices or external web pages that make API calls to GroveStreams. Api keys can have very granular API rights assigned to them and can be restricted from devices with specific IP addresses or from specified domains. The api_key token is not the api_key resource UID, it is the api key's secret key. API keys are created and managed by a GroveStreams organization owner. The org token is not required when the api_key token is being used.
"Authorization: Bearer **AccessToken**" HTML Header (OAuth 2.0)

OAuth is used for cases where a user email and password should not be hard-coded or stored in a file or stored on a device. OAuth should also be used when each device should have its own unique security token that expires and needs to be refreshed frequently. GroveStreams is an OAuth 2.0 authorization server and can be used by other APIs such as Amazon's Alexa for authentication. More information can be found on the GroveStreams OAuth Page.

GroveStreams will use the api_key token for API calls passed with both an api_key and a session token.

SSL
GroveStreams supports SSL. Change http to https in the Resource URL to secure your calls to GroveStreams: https://grovestreams.com/api

SSL encryption and decryption come with a performance cost. You will get better performance not using SSL if your data is not sensitive data and allows you to do so.

Request and Response Formats

The GroveStreams HTTP API uses JSON for almost all of its request and response body formats. Why does GroveStreams rely mainly on JSON?

GroveStreams is all about performance and JSON is faster and more scalable than XML
JSON, when formatted, is a standard and is human readable
JSON is supported by all major programming languages, all major browsers and is easy to work with (see www.json.org)

Compression

The GroveStreams HTTP API supports compression for request/response bodies. We highly encourage using compression as it will make your product and GroveStreams more scalable.

Add a request header "Accept-Encoding : gzip, deflate" to your request and GroveStreams will return your request compressed.

Add a request header "Content-Encoding : gzip" to your request when the body is compressed as gzip.

Sever-side Caching

The GroveStreams web servers will cache resource response requests for 10 seconds. This allows our servers to handle viral requests. The GroveStreams user interface frequently appends an argument called "_dc" with a unique number onto its API calls to avoid server caching for users with "Edit" rights.

HTTP Request Errors

GroveStreams has two types of error codes. HTTP status codes and internal error codes. HTTP status codes come back as HTTP status code errors. GroveStreams internal error codes will be part of the response body along with a description of the actual error.

GroveStreams Internal Error Codes
Grove Streams will map its internal error code with the following HTTP status codes:

Internal Error Code	HTTP Status Code	Description
UNKNOWN_EXCEPTION	500	Internal server error
ENTITY_MISSING	404	Resource not found
SESSION_EXPIRED	500	Session token expired due to inactivity. Watch for SESSION_EXPIRED in the response body to determine if a user should be re-authenticated.
RATE_LIMIT_EXCEEDED	403	Call rate limit has been exceeded.
ACCESS_DENIED	403	session or api_key tokens do not have rights for the action (PUT, POST, GET, DELETE) or resource (i.e. component, cycle, unit, ...).
ENTITY_VALIDATION_FAILURE	422	Resource failed validation during a PUT or SAVE. This error will also return a list of all validation warnings and errors.
CAPTCHA_VALIDATION_FAILURE	422	Captcha challenge failed.
REQUEST_VALIDATION_FAILURE	400	Slightly different than an entity validation error. Usually caused by malformed uid keys or other types of parsing errors.
EXPRESSION_PARSING	500	Stream derivation expression parsing error.
EXPRESSION_EVALUATION	500	Stream derivation expression evaluation error.
EXPRESSION_UNKNOWN	500	Stream derivation unknown expression error.
OAUTH_TOKEN_EXPIRED	400	OAuth2 access token expired.
OAUTH_INVALID_CLIENT	401	OAuth2 invalid token.
OAUTH_INVALID_GRANT	400	OAuth2 invalid grant.

List of HTTP status codes

Sample Request Error:
This is an example of the response body when a session has expired.
HTTP status code was: 401 Unauthorized
Response Body was:


					{
   "message": "Session expired.",
  
					"errCode": "SESSION_EXPIRED",
   "success": false

					}

Sample Request Error:
This is an example of a "POST component" where the component definition had warnings and errors.
HTTP status code was: 422 Unprocessable Entity
Response Body was:


					{
   "message": "ERROR: '': Invalid name size. Range is
					1 to 500 characters.<br>WARNING: '/Percent of Memory Used -
					bytes/Variable/var1': Derived stream expression does not contain
					dependent variable name 'var1'.<br>ERROR: '/Percent of Memory
					Used (WOP) - bytes/Variable/free': Functions cannot be performed on
					a stream base cycle.<br>",
   "errCode":
					"ENTITY_VALIDATION_FAILURE",
   "validationResult": {

					    "validation": [

					      {

					        "message": "Invalid name
					size. Range is 1 to 500 characters.",

					        "pathName": "",

					        "itemType": "component",

					        "valMsgType": "ERROR",

					        "itemUid":
					"59d9d98d-bd17-4b7c-a99a-77b49fbad29b"

					      },

					      {

					        "message": "Derived
					stream expression does not contain dependent variable name
					'var1'.",
        
					"pathName": "/Percent of Memory Used - bytes/Variable/var1",

					        "itemType": "stream",

					        "valMsgType": "WARNING",

					        "itemUid":
					"c8886c4c-0b21-4722-b7ae-599c24374a1f"

					      },

					      {

					        "message": "Functions
					cannot be performed on a stream base cycle.",

					        "pathName": "/Percent of
					Memory Used (WOP) - bytes/Variable/free",

					        "itemType": "stream",

					        "valMsgType": "ERROR",

					        "itemUid":
					"1999ddb7-25c0-4d5a-8835-b1c947049633"

					      }
     ]

					  },
   "success": false
 }