CRUD Events

Avatar
SupportTeam

/v2/events/<stream_name>/<login_id> endpoints are used for the creation and retrieval of event data.

 

login_id is optional if an API Basic User is logged in, as that user can only post and retrieve data on its own behalf. However, it is required if an API Business User is logged in. Each posted event belongs to the API Basic User specified or logged in.

Create events

Creates event(s) associated with the specified user or the current session Basic User.

Summary

  • Endpoint: /v2/events/<stream_name>/<login_id>
  • Method: POST
  • Permissions: This operation is permitted for Basic User and Business User roles. A user with the Basic User role can only see its own data. 

Headers

Content-Type: application/json
Accept: application/json
Cookies: < login cookies >

Body

  • event_data (required): JSON object containing data to be written
    • See Data Types for information on the types of values that can be sent
  • observed_at: event timestamp
    • Default: received_at time
    • Type:  ISO8601-formatted text string, including timezone
  • add_client_ip: will put the client IP address into the event's event_data as the tag ip_address. 
    • Default: false
    • Type: boolean

Can be multiple items, one JSON document per line (with newline character between each JSON document). The POST body has a maximum limit of 10MB.

  • Example of single data event

    {"observed_at": "2014-06-11T02:11:25.076001Z", "event_data": {"sensor1": 37.3, "sensor2": 183}}

  • Example of multiple data events

    CORRECT

    {'observed_at': '2014-06-11T02:11:26.157759Z', 'event_data': {'sensor1': 38.6}}
    {'observed_at': '2014-06-11T02:12:27.458693Z', 'event_data': {'sensor1': 39.4}}

    INCORRECT

    {'observed_at': '2014-06-11T02:11:26.157759Z', 'event_data': {'sensor1': 38.6}}{'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}

HTTP Response

200 OK

  • Event(s) successfully created. Returns number of events created.

400 BAD REQUEST

  • The request was missing parameters or the parameters were not formatted correctly.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.

Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"biz_user","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X POST -k -H 'Content-Type: application/json' -i https://api.mediumone.com/v2/events/raw/api_user -d '{"observed_at": "2015-01-10T00:00:00.000-0800", "event_data": {"sensor1" : 38.6}}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'biz_user', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api.mediumone.com/v2/events/raw/api_user'
data = {'observed_at': '2015-01-10T00:00:00.000-0800', 'event_data': {'sensor1' : 38.6}}

response = session.post(url=url, data=json.dumps(data), headers=headers)

 

Retrieve events

Summary

  • Endpoint: /v2/events/<stream_name>/<login_id>
  • Method: GET
  • Permissions: This operation is permitted for Basic User and Business User roles. A user with the Basic User role can only see its own data. 

Headers

Accept: application/json
Cookies: < login cookies >

Path

URL-encoded parameters, all optional:

  • since:  fetches all data after specified time
    • Type: ISO8601 format timestamp, including timezone.
  • until:  fetches all data before specified time
    • Type: ISO8601 format timestamp, including timezone.
  • limit: limits the number of results.
    • Default: 10000
    • Type: a whole number up to a maximum of 10,000
      • For retrieving more than this number of data events, since and until parameters can be used to do multiple queries over different time spans.
  • sort_by: value to sort results by.
    • Type: string, either "observed_at", "received_at" or "internal".
      • "internal" is roughly equivalent to "received_at" but sorts by event_ids, so events received at the same millisecond may not sort in the same order as "received_at".
      • The advantage of the "internal" sort order is that the queries are faster, especially when a user isn't specified.
    • Required with use of sort_direction
  • sort_direction: direction to sort results.
    • Default: "asc"
    • Type: string, either "asc" or "desc" for ascending and descending. If not specified, "sort_direction" is considered to be "asc".
    • Specifying "sort_direction" without "sort_by" will result in an error.
  • include: Fetches data of the specified tag
  • exclude: Fetches all data, omitting the specified tag
  • filters: a JSON object specifying rules to restrict the returned data. Refer to Building Filters for more information

HTTP Response

200 OK

  • events successfully read. The response body should contain one JSON document per line, with no specific ordering: 
    {"observed_at": "< ISO_observed_at >", "event_data": {event_data}, "stream":"raw", "login_id": "< some_id >"}
    {"observed_at": < ISO_observed_at >, "event_data": {event_data}, "stream":"raw", "login_id": "< some_id >"}

400 BAD REQUEST

  • The request was missing parameters or the parameters were not formatted correctly.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to view that user’s data.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.

Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -X POST -k -H 'Content-Type: application/json' -H 'Accept: application/json' -i 'https://api.mediumone.com/v2/login' -d '{"login_id": "biz_user", "password": "123456", "api_key": "Abcdefghijklmnopqrstuvwxyz0123456789"}'

# get data
curl -b cookies.txt -X GET -k -H 'Accept: application/json' 'https://api.mediumone.com/v2/events/raw/api_user?since=2015-01-10T00%3A00%3A00.000-0800&limit=100&include=$.event_data.tagname'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'biz_user', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

# Login
session = requests.session()
response = session.post('https://api.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api.mediumone.com/v2/events/raw/api_user'
headers = {'Accept': 'application/json'}
params = {"since":"2015-01-10T00:00:00.000-0800", "until":"2015-01-17T00:00:00.000-0800", "limit":100, "include":"$.event_data.tagname"}

# GET
response = session.get(url=url, params=params, headers=headers)

 

 

Update events

Updates an event's event_data and/or observed_at. 

Note: if observed_at is updated to an earlier timestamp, last_value analytics queries won't immediately reflect the new last value

Summary

  • Endpoint: /v2/events/<stream_name>/<login_id>
  • Method: PATCH
  • Permissions: This operation is permitted for Basic User and Business User roles. A user with the Basic User role can only see its own data. 

Headers

Content-Type: application/json
Accept: application/json
Cookies: < login cookies >

Body

  • event_data (required): JSON object containing data to be written
    • See Data Types for information on the types of values that can be sent
  • event_id (required): ID of event to update
  • observed_at: event timestamp
    • Default: original observed_at time
    • Type:  ISO8601-formatted text string, including timezone
  • add_client_ip: will put the client IP address into the event's event_data as the tag ip_address. 
    • Default: false
    • Type: boolean

Can be multiple items, one JSON document per line (with newline character between each JSON document). The PATCH body has a maximum limit of 10MB.

  • Example of single data event

    {"observed_at": "2014-06-11T02:11:25.076001Z", "event_data": {"sensor1": 37.3, "sensor2": 183}}

  • Example of multiple data events

    CORRECT

    {'observed_at': '2014-06-11T02:11:26.157759Z', 'event_data': {'sensor1': 38.6}}
    {'observed_at': '2014-06-11T02:12:27.458693Z', 'event_data': {'sensor1': 39.4}}

    INCORRECT

    {'observed_at': '2014-06-11T02:11:26.157759Z', 'event_data': {'sensor1': 38.6}}{'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}

HTTP Response

202 ACCEPTED

  • The request to update the event is being processed.

400 BAD REQUEST

  • The request was missing parameters or the parameters were formatted incorrectly.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.

Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"biz_user","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X PATCH -k -H 'Content-Type: application/json' -i https://api.mediumone.com/v2/events/raw/api_user -d '{"observed_at": "2015-01-10T00:00:00.000-0800", "event_id": 1234, "event_data": {"sensor1" : 37.6}}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'biz_user', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api.mediumone.com/v2/events/raw/api_user'
data = {'observed_at': '2015-01-10T00:00:00.000-0800', 'event_id': 1234, 'event_data': {'sensor1' : 38.6}}

response = session.patch(url=url, data=json.dumps(data), headers=headers)

 

Delete an event

Deleting events via API is not currently supported. See How to delete data for information about the available options to delete your events.