Mashery Reporting Event Post API Guide

Using the API

The Reporting Event Post API allows other web-services tools to post event log data into Mashery’s reporting and analytics engine. Mashery places quota and throttle limits on the number of HTTP POSTs that can be made against the Reporting Event Post API service. The best practice is to include several log entries per POST call, instead of sending a large number of frequent requests to the service. Mashery may also place limits on how much data can be posted in a single call. The best practice is to include a maximum of 10,000 log entries in a single post. When you integrate with Mashery using this API, you must take into consideration that, if requests against the service fail due to limits, the requests need to be re-tried.

Authorization

Contact your Mashery account manager for a key and secret for each customer site that uses the combined solution with you as the partner and Mashery. The partner product must provide a way to input this key and secret in customer installations of the combined product.

The API Signature

The following table describes the API signature:

Element	Value/Description
Host	partners.api.mashery.com
Endpoint	/reporting
Method	POST
Headers:	Content-Type: application/x-gzip or text/plain X-Mashery-Signature: HMAC-SHA256(lcase(apikey=<apikey>&timestamp=<timestamp>)body, secret)
URL parameters	¢ apikey ¢ timestamp

Performing a Post

Your product may post plaintext log data or a gzip of that data. You must set Content-Type properly for appropriate type: text/plain for plain text or application/x-gzip for gzip. data.

When sending data with a Content-Encoding, such as plain-text data encoded using gzip, the body used in the calculations is the raw data after the data is decoded (which would be the raw data prior to having been encoded from the sender).

The signature is calculated by concatenating the apikey and timestamp parameters in that order followed by the raw post body and performing an SHA256 HMAC over that value using the supplied secret. The HMAC value is lowercase hexits.

Signature Example

http://partners.api.mashery.com/reporting?apikey=1234&timestamp=1349378903

Raw POST Body:

abcdefghijklmnopqrstuvwxyz

Value to perform HMAC over:

apikey=1234&timestamp=1349378903abcdefghijklmnopqrstuvwxyz

Issued secret:

mysecret

SHA256 Calclulation:

SHA256('apikey=1234&timestamp=1349378903abcdefghijklmnopqrstuvwxyz','mysecret')

Signature:

2eca11949d8a9bd9ed729e722e63bd8cdb715f5e1a860f6ba98fb1af6c045220

Formulating the Post Body

The POST Body contains the log data to be submitted and consists of log records that must conform syntactically to the log format specification below:

Field	Type	Description	Example
server_name	string	This is a “Mashery Internal” field. Partner product must supply -	-
src_ip	string	Originating IP address of the call. This field is used in report “Map Overlay” in API usage that shows geo origin of API calls. Partner product must supply this value if available or -	158.151.240.64
ident	string	This is a “Mashery Internal” field. Partner product must supply -	-
record_type	string	This is a “Mashery Internal” field. Partner product must supply -	-
log_timestamp	string	Timestamp of the log entry. This must be GMT and is needed by Mashery reporting engine for basic log handling; this is the time that drives where the counts appear in the time aggregations.	[12/Jun/2012:21:53:03 +0000]
method – http_version	string	HTTP request method (GET, POST, PUT, DELETE, HEAD etc.) and HTTP version (1.1 or 1.0). Partner must supply these values with a – in between	“GET - HTTP/1.1”
bytes	number	Bytes returned in the response. Partner product must supply the right value	11111
status	string	Three-digit HTTP response code returned for the request. Partner product must supply this value – used in System Status / Errors reports	200
referrer	string	This is a “Mashery Internal” field. Partner product must supply “-”	“-”
User_Agent	string	This is a “Mashery Internal” field. Partner product must supply -	“-”
request_id	string	Mashery Internal ID for this request. Partner product must supply this value by generating in the below format: 0_<service_dev_key>_<service_key>
service_dev_key	string	The API key that a developer obtains at the time of registering to use customer’s API.
service_key	string	The API ID that is generated when customer’s API is configured in Mashery API Settings page.	0_u2cbu87r6f2q3m66j6yc2uce_ ygnj8v68nqb76akfzetwb799
referrer_domain	string	This is a “Mashery Internal” field. Partner product must supply -	“-”
proxy_worker	string	This is a “Mashery Internal” field. Partner product must supply -	“-”
api_method	string	API method called. Partner product must supply the right method name for all the method level reports to work	“GetCompanyDetailRequest”
cache_hit	number	Boolean value for whether or not the response was delivered from the cache. 1=Partner product responded from cache, 0=Partner product did not. This is used in the cache hit reports. If this is not available, Partner product must supply 0	0
proxy_error_code	string	This is a “Mashery Internal” field. Partner product must supply -	-
exec_time	number	Elapsed time, in seconds, from the moment the request was received by the Partner to the moment Partner sent a response. This is used in latency related reports. If unavailable, Partner product must supply 0	5.555555
remote_total_time	number	Elapsed time, in seconds, the backend call took. (This is the time from when the request was attempted by the Partner product to the time header information was received, not the last byte of the response). This is used in latency related reports. If unavailable, Partner product must supply 0	4.444444
connect_time	number	Of the remote_total_time, how long, in seconds, it took to establish a connection. This is used in latency reports. If unavailable, Partner product must supply 0	0.333333
pre_transfer_time	number	Of the remote total_time, how long, in seconds, it took AFTER establishing a connection BEFORE the first byte was received by Partner product. This is used in latency reports. If unavailable, Partner product must supply 0	0.222222
reference_guid	string	This is a “Mashery Internal” field. Partner product must supply -	-

Example: Sample Data for All Allowable Fields

- 158.151.240.64 - - [12/Jun/2012:21:53:03 +0000] "GET - HTTP/1.1" 11111 200 "-" "-" 0_u2cbu87r6f2q3m66j6yc2uce_ygnj8v68nqb76akfzetwb799 "-" "-" "GetCompanyDetailRequest" 0 - 5.555555 4.444444 0.333333 0.222222 -

Example: Sample Data for Minimum Parsable Log Entry

- - - - [12/Jun/2012:21:53:03 +0000] "GET - HTTP/1.1" 0 200 "-" "-" 0_u2cbu87r6f2q3m66j6yc2uce_ ygnj8v68nqb76akfzetwb799 "-" "-" "-" 0 - 0 0 0 0 -

Response Codes

Upon submission of the data, the Mashery server responds with one of the following status codes:

200 - the data was successfully accepted by Mashery for processing.

403 - apikey and/or signature is invalid

403 - Over Queries Per Second Limit

403 - Over Rate Limit

403 - Service Over Queries-per-Second-Limit

415 - Unsupported Media Type (content must be application/x-gzip or text/plain)

500 - Unexpected error

503 - Service unavailable

596 - HTTP method or endpoint used is incorrect

version 5 as of 7 years ago by Jeremy Pollock