Upload
others
View
17
Download
0
Embed Size (px)
Citation preview
Page 1
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
Version
Number
Date Author Changes
1 Nov 2015 Sam Smith
2 Jun 2016 Sam Smith Branding updated
3 Sep 2016 Sam Smith Published
4 Feb 2017 Sam Smith Added web interface section
Updated API error codes
Branding updated
5 Jul 2017 Sam Smith Branding updated
Page 2
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
Contents 1 Introduction ......................................................................................................................................... 3
2 Enabling the Interface ....................................................................................................................... 3
3 Margay API .......................................................................................................................................... 4
3.1 ping: ............................................................................................................................................. 4
3.2 getCookieName: ....................................................................................................................... 4
3.3 login: ............................................................................................................................................. 4
3.3.1 Successful response: ............................................................................................................. 5
3.3.2 Fields ......................................................................................................................................... 5
3.3.3 Errors ......................................................................................................................................... 5
3.4 getAuthenticationInformation ................................................................................................ 8
3.4.1 Successful response: ............................................................................................................. 8
3.4.2 Fields ......................................................................................................................................... 8
3.4.3 Errors ......................................................................................................................................... 9
3.5 getThroughputInformation .................................................................................................... 12
3.5.1 Successful responses: .......................................................................................................... 12
3.5.2 Fields ....................................................................................................................................... 12
3.5.3 Errors ....................................................................................................................................... 13
3.6 logout ......................................................................................................................................... 16
3.6.1 Successful response: ........................................................................................................... 16
3.6.2 Fields ....................................................................................................................................... 16
3.6.3 Errors ....................................................................................................................................... 16
3.7 Coding Examples .................................................................................................................... 18
3.7.1 PHP cURL ............................................................................................................................... 18
4 Web Interface ................................................................................................................................... 19
4.1 Different Time Period Views ................................................................................................... 21
Page 3
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
1 Introduction The Margay service enables customers to request data from Eseye servers on a number of
important events in the previous time period.
The Margay service has two delivery methods:
An app agnostic API
A web interface hosted by Eseye
For the API:
The requests are sent through to the Network Information and Management (NIAM) JSON
API. This system is designed to have requests sent frequently and from automated sources,
this collection of JSON formatted data can then be collated by a customer to convert the
data into useful information.
This API sections of this document uses the Postman app only as an example, the API is app
agnostic. The Postman User Guide can be found at https://www.eseye.com/wp-
content/uploads/8314-Postman-User-Guide.pdf. Postman allows you to download the
request in a coding language of your choice, using the Generate Code button.
For the web interface:
The requests are viewable through a collection of graphs.
The time period that the data is for is pre-agreed between Eseye and individual customers
dependent on the requirements and nature of the devices being used.
The system currently provides data on the number of SIM card authentications, and how
much data has been sent to and from the estate.
2 Enabling the Interface To enable the use of Margay on your account speak to your Eseye Account Manager.
To run the requests you will require: your Margay username, password, account portfolioID.
Page 4
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3 Margay API
3.1 ping: This function tests whether the server running. To test the interface in Postman app use the
details shown below, to download a code example of this request use the Generate Code
button:
Request URL: https://margay.eseye.com/Japi/Niam/ping
Command: ‘Post’
Requires no formatted text.
A successful response will read "pong", if this is not returned it means that either the Eseye
server is down or that the request was incorrect.
3.2 getCookieName: This function returns the name of the cookie that is used to keep the session logged in. To test
the interface in Postman app use the details shown below, to download a code example of
this request use the Generate Code button:
Request URL: https://margay.eseye.com/Japi/Niam/getCookieName
Command: ‘Post’
Requires no formatted text.
A successful response will read "examplecookie" (with this being an example), if this is not
returned it means that either the Eseye server is down or that the request was incorrect.
3.3 login: This function logs the user on. If you do not log out, but an attempt is made to log in, the
previous user will be logged out, regardless of whether the new login attempt is successful. To
test the interface in Postman app use the details shown below, to download a code
example of this request use the Generate Code button:
Request URL: https://margay.eseye.com/Japi/Niam/login
Command: ‘Post’
Requires the following formatted JSON text:
{
"username" : "exampleusername" ,
"password" : "examplepassword"
}
Click the blue ‘Send’ button.
All responses are when viewed in the pretty form (default setting)
Page 5
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.3.1 Successful response: Successful responses will look as follows:
{
"cookie": "ExampleCookie",
"status": {
"status": "OK",
"errorCode": "",
"errorMessage": ""
}
}
3.3.2 Fields 3.3.2.1 "cookie"
This displays the name of the cookie that is used to keep the session logged in, this line is the
same as the getCookieName function.
3.3.2.2 "status"
This displays the status of the request, will display ERR if the request is unsuccessful, and OK if
successful.
3.3.2.3 "errorCode"
This displays an error code if the request is unsuccessful, if successful will be blank.
3.3.2.4 "errorMessage"
This displays an explanation of the error if the request is unsuccessful, if successful will be
blank.
3.3.3 Errors E0000 – Unknown username or password
{
"status": {
"status": "ERR",
"errorCode": "E0000",
"errorMessage": "Unknown username or password"
}
}
This indicates that the password value was entered incorrectly.
Page 6
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.3.3.1 E0100 – Unknown username or password
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E0100",
"errorMessage": "Unknown username or password"
}
}
This indicates that the username or password value or parameter was entered incorrectly.
3.3.3.2 E0101 – Invalid JSON
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E0101",
"errorMessage": "Invalid JSON"
}
}
This indicates that the JSON text was structured incorrectly. Check that your JSON text follows
the format described. Note this error can be received due to Microsoft Word style text being
entered, as some characters are slightly different between Microsoft Word and ASCII. To
avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text
is entered.
3.3.3.3 Could not get any response:
This error message will display as follows:
This indicates that either you are not connected to the internet or one or more of the
following sections of the Request URL were entered incorrectly. http ://
.eseye.com/
Page 7
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.3.3.4 <!DOCTYPE html>:
This error message will begin as follows:
This indicates that one or more of the following sections of the Request URL were entered
incorrectly. Margay
Page 8
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.4 getAuthenticationInformation This function retrieves a summary of authentication information over the last time period. To
test the interface in Postman app use the details shown below, to download a code
example of this request use the Generate Code button:
Request URL: https://margay.eseye.com/Japi/Niam/getAuthenticationInformation
Command: ‘Post’
Requires the following formatted JSON text:
{
"username" : "exampleusername" ,
"password" : "examplepassword" ,
"portfolioID" : "exampleportfolioid"
}
All responses are when viewed in the pretty form (default setting)
3.4.1 Successful response: Successful responses will look as follows:
{
"status": {
"status": "OK",
"errorCode": "",
"errorMessage": ""
},
"auth_count": [
{
"mcc": "234",
"mnc": "10",
"start_date": "2016-08-16 10:07:47",
"stop_date": "2016-08-16 10:08:47",
"auth-accept": "1"
}
]
}
3.4.2 Fields 3.4.2.1 "status"
This displays the status of the request, will display ERR if the request is unsuccessful, and OK if
successful.
3.4.2.2 "errorCode"
This displays an error code if the request is unsuccessful, if successful will be blank.
Page 9
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.4.2.3 "errorMessage"
This displays an explanation of the error if the request is unsuccessful, if successful will be
blank.
3.4.2.4 "auth_count"
This is the heading for the following object.
3.4.2.5 "mcc"
This displays the Mobile Country Code.
3.4.2.6 "mnc"
This displays the Mobile Network Code.
3.4.2.7 "start_date"
This displays the start of the period in UTC.
3.4.2.8 "stop_date"
This displays the end of the period in UTC.
3.4.2.9 "auth_accept"
This displays the number of devices authenticated in the period.
3.4.3 Errors 3.4.3.1 E0000 – Unknown username or password
{
"status": {
"status": "ERR",
"errorCode": "E0000",
"errorMessage": "Unknown username or password"
}
}
This indicates that the password value was entered incorrectly.
3.4.3.2 E0100 - Unknown username or password
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E0100",
"errorMessage": "Unknown username or password"
}
}
This indicates that the username value or parameter or the password parameter or the
portfolioID value was entered incorrectly.
Page 10
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.4.3.3 E0101 – Invalid JSON
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E0101",
"errorMessage": "Invalid JSON"
}
}
This indicates that the JSON text was structured incorrectly. Check that your JSON text follows
the format described. Note this error can be received due to Microsoft Word style text being
entered, as some characters are slightly different between Microsoft Word and ASCII. To
avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text
is entered.
3.4.3.4 E9991 – No Recent data available for user
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E9991",
"errorMessage": "No recent data available for user"
}
}
This indicates that there were no data was passed within the last time period.
3.4.3.5 E9992 – User disabled for configuration
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E9992",
"errorMessage": "User disabled for configuration"
}
}
This indicates that the PortfolioID parameter was entered incorrectly
3.4.3.6 E9998 - Other error
This means that the session should be restarted, if the appears repeatedly contact Eseye
Support team details found at https://www.eseye.com/contact-us/ )
Page 11
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.4.3.7 Could not get any response:
This error message will display as follows:
This indicates that either you are not connected to the internet or one or more of the
following sections of the Request URL were entered incorrectly. http ://
.eseye.com/
3.4.3.8 <!DOCTYPE html>:
This error message will begin as follows:
This indicates that one or more of the following sections of the Request URL were entered
incorrectly. Margay
Page 12
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.5 getThroughputInformation This function retrieves a summary of data sent and received over the last time period. To test
the interface in Postman app use the details shown below, to download a code example of
this request use the Generate Code button:
Request URL: https://margay.eseye.com/Japi/Niam/getAuthenticationInformation
Command: ‘Post’
Requires the following formatted JSON text:
{
"username" : "exampleusername" ,
"password" : "examplepassword" ,
"portfolioID" : "exampleportfolioid"
}
All of these responses are when viewed in the pretty form (default setting)
3.5.1 Successful responses: Successful responses will look as follows:
{
"status": {
"status": "OK",
"errorCode": "",
"errorMessage": ""
},
"data_count": [
{
"mcc": "234",
"mnc": "10",
"databytes_mo": "517",
"databytes_mt": "284",
"start_date": "2016-09-14 16:12:00",
"stop_date": "2016-09-14 16:13:00"
}
]
}
3.5.2 Fields 3.5.2.1 "status"
This displays the status of the request, will display ERR if the request is unsuccessful, and OK if
successful.
3.5.2.2 "errorCode"
This displays an error code if the request is unsuccessful, if successful will be blank.
Page 13
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.5.2.3 "errorMessage"
This displays an explanation of the error if the request is unsuccessful, if successful will be
blank.
3.5.2.4 "auth_count"
This is the heading for the following object.
3.5.2.5 "mcc"
This displays the Mobile Country Code.
3.5.2.6 "mnc"
This displays the Mobile Network Code.
3.5.2.7 "start_date"
This displays the start of the period in UTC.
3.5.2.8 "stop_date"
This displays the end of the period in UTC.
3.5.2.9 "databytes_mo"
This displays the number of bytes sent in the period.
3.5.2.10 “databytes_mt”
This displays the number of bytes received in the period.
3.5.3 Errors
3.5.3.1 E0000 – Unknown username or password
{
"status": {
"status": "ERR",
"errorCode": "E0000",
"errorMessage": "Unknown username or password"
}
}
This indicates that the password value was entered incorrectly.
3.5.3.2 E0100 - Unknown username or password
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E0100",
"errorMessage": "Unknown username or password"
}
}
This indicates that the username value or parameter or the password parameter or the
portfolioID value was entered incorrectly.
Page 14
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.5.3.3 E0101 – Invalid JSON
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E0101",
"errorMessage": "Invalid JSON"
}
}
This indicates that the JSON text was structured incorrectly. Check that your JSON text follows
the format described. Note this error can be received due to Microsoft Word style text being
entered, as some characters are slightly different between Microsoft Word and ASCII. To
avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text
is entered.
3.5.3.4 E9991 – No Recent data available for user
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E9991",
"errorMessage": "No recent data available for user"
}
}
This indicates that there were no authentications within the last time period.
3.5.3.5 E9992 – User disabled for configuration
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E9992",
"errorMessage": "User disabled for configuration"
}
}
This indicates that the PortfolioID parameter was entered incorrectly
3.5.3.6 E9998 - Other error
This means that the session should be restarted, if the appears repeatedly contact Eseye
Support team details found at https://www.eseye.com/contact-us/ )
3.5.3.7 Could not get any response:
This error message will display as follows:
Page 15
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
This indicates that either you are not connected to the internet or one or more of the
following sections of the Request URL were entered incorrectly. http ://
.eseye.com/
3.5.3.8 <!DOCTYPE html>:
This error message will begin as follows:
This indicates that one or more of the following sections of the Request URL were entered
incorrectly. Margay
Page 16
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.6 logout This function logs out the current user, the whole session in Tigrillo is destroyed. To test the
interface in Postman app use the details shown below, to download a code example of this
request use the Generate Code button:
Request URL: https://margay.eseye.com/Japi/Niam/logout
Command: ‘Post’
Requires no formatted text.
All of these responses are when viewed in the pretty form (default setting)
3.6.1 Successful response: Successful responses will look as follows:
{
"status": {
"status": "OK",
"errorCode": "",
"errorMessage": ""
}
}
3.6.2 Fields
3.6.2.1 "status"
This displays the status of the request, will returned either ERR or OK.
3.6.2.2 "errorCode"
This displays an error code if the request is unsuccessful, if successful will be blank.
3.6.2.3 "errorMessage"
This displays an explanation of the error if the request is unsuccessful, if successful will be
blank.
3.6.3 Errors
3.6.3.1 E0006 – Permission denied
This error message will display as follows:
{
"status": {
"status": "ERR",
"errorCode": "E0006",
"errorMessage": "Permission denied"
}
}
This indicates that the user is already logged out.
Page 17
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.6.3.2 E9998 - Other error
This means that the session should be restarted, if the appears repeatedly contact Eseye
Support team details found at https://www.eseye.com/contact-us/ )
3.6.3.3 Could not get any response:
This error message will display as follows:
This indicates that either you are not connected to the internet or one or more of the
following sections of the Request URL were entered incorrectly. http ://
.eseye.com/
3.6.3.4 <!DOCTYPE html>:
This error message will begin as follows:
This indicates that one or more of the following sections of the Request URL were entered
incorrectly. Margay
Page 18
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
3.7 Coding Examples All of these examples are using the getThroughputInformation
3.7.1 PHP cURL <?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL =>
"https://margay.eseye.com/Japi/Niam/getthroughputinformation"
,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\r\n\"username\" :
\"ExampleUsername\" ,\r\n\"password\" : \"ExamplePassword\"
,\r\n\"portfolioID\" : \"ExamplePortfolioID\"\r\n}",
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: application/json",
"postman-token: 823e2f1c-d843-c90f-9d07-107061f5e417"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Page 19
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
4 Web Interface The Web interface is located at: http://margay.eseye.com/Niam/index.
Enter your account details and press the ‘Sign In’ button.
This should reveal the ‘Country Selector Page’:
Page 20
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
Enter the MCC desired and whether you want to see the number of authentications or the
amount of data passed.
As long as there is data for the selected MCC a graph will appear:
Scroll down to view the table of data used to create the graph.
Page 21
+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
4.1 Different Time Period Views The default view is the last 24 hours.
To alter the period shown use the period select scroll.
To view a larger period use the ‘Return to month’ or the ‘Return to day’ buttons.
To view a smaller period click on the headings in the table.