Skip to content

Latest commit

 

History

History
152 lines (103 loc) · 2.79 KB

restapi.md

File metadata and controls

152 lines (103 loc) · 2.79 KB
Raw

REST API

Here is the description of Seismo REST interface.

Authentication

Clients have to authenticated in order to access API. We used simple authentication flow, based on GitHub. Authenticated users are generating Personal Tokens.

There is a configuration file, there you specify GitHub accounts that are permitted to access API.

// config.js

var config = {
	auth: {
		users: [
			'alexanderbeletsky',
			'voronianski'
		]
	}
};

API endpoint,

HTTP POST http://analytics.host/auth

var payload = {
	token: 'GITHUB_PERSONAL_TOKEN'
};

If personal token belongs to user specified in configuration file, the permissions are granted. Access token is returned to client. Access token is used as either X-Access-Token request header, or ?access_token= query parameter or token cookie value.

Application ID

Application ID is association between events and application that generates it. One server could handle as many as needed.

Posting Events

HTTP POST http://analytics.host/api/events/:app-id

{
	event: 'event',
	data: {}
}

With event id and event name,

HTTP POST http://analytics.host/api/events/:app-id

{
	event: {id: 'app-start', event: 'application started'},
	data: {}
}

With additional event payload,

HTTP POST http://analytics.host/api/events/:app-id

{
	event: 'application started',
	data: {environment: 'production'}
}

Querying Events

All events generated by app,

HTTP GET http://analytics.host/api/events/:app-id

By event name,

HTTP GET http://analytics.host/api/events/:app-id?event=search%20executed

By event id,

HTTP GET http://analytics.host/api/events/:app-id?id=app-start

Today events,

HTTP GET http://analytics.host/api/events/:app-id?date=today

Or by date,

HTTP GET http://analytics.host/api/events/:app-id?date=2014-09-26

Or combination,

HTTP GET http://analytics.host/api/events/:app-id?event=search%20executed&date=today

Building Reports

Events for one hour for given date,

HTTP GET http://analytics.host/api/reports/hour/:app-id?hour=6&date=2013-09-29

By given date,

HTTP GET http://analytics.host/api/reports/day/:app-id?date=2013-09-29

By given week,

HTTP GET http://analytics.host/api/reports/week/:app-id?week=2013-09-29

By given month,

HTTP GET http://analytics.host/api/reports/month/:app-id?month=2013-09-29

By any period,

HTTP GET http://analytics.host/api/reports/period/:app-id?from=2013-09-10&to=2013-09-13

Grouping Events

By attribute,

HTTP GET http://analytics.host/api/groups/:app-id?id=user-logged&attr=email&from=2013-12-10&to=2013-12-12