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

Docs Navigation