Multitech MultiConnect rCell MTR-H5 Mode d’emploi

MultiConnect R

rCell API

Developer Guide

MultiConnect R

rCell API Developer Guide

Models: MTR-H5, MTR-H6, MTR-G3, MTR-EV3, MTR-C2 (Software Version 3.0.9)

S000576, Version 1.0

This publication may not be reproduced, in whole or in part, without prior expressed written permission from Multi-Tech Systems,

2014, by Multi-Tech Systems, Inc.

Multi-Tech Systems, Inc. makes no representations or warranties with respect to the contents hereof and speciﬁcally disclaims any

implied warranties of merchantability or ﬁtness for any particular purpose. Furthermore, Multi-Tech Systems, Inc. reserves the right

to revise this publication and to make changes from time to time in the content hereof without obligation of Multi-Tech Systems,

Inc. to notify any person or organization of such revisions or changes. Check Multi-Techs web site for current versions of our product

documentation.

Revision History

Revision Date Author Description

0.1 1/4/13 Jason Reiss Initial Document

0.2 1/30/13 Jason Reiss Auto-Gen Script and Reference Updates

0.3 2/27/13 Jason Reiss Removed Unused Elements

0.4 3/11/13 Jason Reiss Updated Logout Instructions

0.5 6/1/13 Sean Godinez Updated Auto-Gen Scripts and Document Content

0.6 6/6/13 Sean Godinez Added Statistics and Help Section

0.7 11/21/13 Sean Godinez Updated for rCell v3.0.9

0.8 12/2/13 Sean Godinez Added ’DRAFT’ Watermark

0.9 12/4/13 Jason Reiss Updated document layout

1.0 1/15/14 Sean Godinez Release

Trademarks

Multi-Tech Registered Trademarks: MultiConnect, Multi-Tech, and the Multi-Tech logo.

All other products and technologies are the trademarks or registered trademarks of their respective holders.

Contacting Multi-Tech

Knowledge Base

The Knowledge Base provides immediate access to support information and resolutions for all Multi-Tech products.

Visit http://www.multitech.com/kb.go.

Installation Resources

To download manuals, ﬁrmware, and software, visit http://www.multitech.com/setup/product.go.

Support Portal

To create an account and submit a support case directly to our technical support team, visit: https://support.multitech.com.

Technical Support

Business Hours: M-F, 9am to 5pm CST

Country By Email By Phone

Europe, Middle East, Africa: [email protected] +(44) 118 959 7774

U.S., Canada, all others: [email protected] (800) 972-2439 or (763) 717-5863

World Headquarters

Multi-Tech Systems, Inc.

2205 Woodale Drive

Mounds View, MN 55112

United States

Phone: 800-328-9717 or 763-785-3500

Fax: 763-785-9874

Warranty

To read the warranty statement for your product, please visit: http://www.multitech.com/warranty.go.

2Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide

CONTENTS

Contents

1 Introduction 5

2 Requests 5

2.1 MakingRequests ........................................... 5

2.2 LoggingIn............................................... 6

2.3 LoggingOut.............................................. 7

2.4 WhoAmI ............................................... 7

2.5 PassingJSONData.......................................... 8

2.6 SavingChanges ............................................ 8

2.7 Selecting a Version of an API Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.8 ElementDescriptions ......................................... 8

2.9 URIParameters ............................................ 9

3 Responses 10

3.1 Success................................................. 10

3.1.1 Successresponseformat ................................... 10

3.2 Error.................................................. 10

3.2.1 Errorresponseformat..................................... 10

3.2.2 ErrorCodes .......................................... 11

4 Commands and Collections 12

4.1 Commands............................................... 12

4.2 Collections............................................... 13

4.3 CollectionDetails ........................................... 13

4.3.1 autoDialout ......................................... 13

4.3.2 autoReboot ......................................... 14

4.3.3 bluetooth........................................... 14

4.3.4 brand ............................................. 14

4.3.5 ddns ............................................. 15

4.3.6 devices ............................................ 15

4.3.7 dhcp ............................................. 16

4.3.8 dns .............................................. 16

4.3.9 ﬁlters ............................................. 16

4.3.10 gccp ............................................. 17

4.3.11 gps .............................................. 17

4.3.12 greTunnels .......................................... 18

4.3.13 ipPipes ............................................ 18

4.3.14 ipsecTunnels ......................................... 19

4.3.15 lan .............................................. 20

4.3.16 nat .............................................. 20

4.3.17 networks ........................................... 21

4.3.18 ppp .............................................. 21

4.3.19 remoteAccess ........................................ 23

4.3.20 remoteManagement ..................................... 23

4.3.21 routes ............................................ 24

4.3.22 serial ............................................. 24

4.3.23 sntp ............................................. 24

4.3.24 syslog ............................................ 25

4.3.25 system ............................................ 25

4.3.26 users ............................................. 26

4.3.27 wiﬁ .............................................. 27

Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide 3

CONTENTS

5 Statistics 28

5.1 dns .................................................. 29

5.2 gps .................................................. 29

5.3 gre .................................................. 29

5.4 ipsec ................................................. 30

5.5 lan .................................................. 30

5.6 modbus ................................................ 31

5.7 ppp .................................................. 31

5.8 serial ................................................. 32

5.9 service ................................................ 32

5.10 wlan ................................................. 33

6 Appendix 34

6.1 RESTArchitecture .......................................... 34

6.2 JSONData .............................................. 34

6.3 Examples................................................ 34

6.3.1 UsingCurltologin...................................... 34

6.3.2 UsingCurltoenablePPP................................... 35

6.3.3 Using Curl to add a ﬁrewall DNAT rule . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.3.4 Using Curl to add a ﬁrewall ﬁlter rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

6.3.5 Using Curl to delete a ﬁrewall ﬁlter rule by name . . . . . . . . . . . . . . . . . . . . . . 37

6.3.6 Using Curl to delete a ﬁrewall ﬁlter rule by index . . . . . . . . . . . . . . . . . . . . . . 37

6.3.7 Using Curl to save current conﬁgurations and reboot . . . . . . . . . . . . . . . . . . . . 37

4Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide

2 REQUESTS

1 Introduction

The MultiConnect R

rCell is a cellular router that uses a RESTful JSON API for managing conﬁgurations, polling

statistics, and issuing commands. This document provides information on the design, patterns, and methods

within the rCell API. The Appendix of this document has additional information for those unfamiliar with the

REST architecture or JSON data format. For additional examples and use-cases, explore the JavaScript within

the rCell website, speciﬁcally https://[rcell ip]/js/api.js.

2 Requests

All API requests will be directed to the https://[rcell ip]/api url. The majority of requests follow the same RESTful

pattern. Following the api url will be a collection name or a command directive. For example, information on

the current DHCP settings can be found in the DHCP collection at https://[rcell ip]/api/dhcp. A full list of

collections and commands can be found in section 4. For all examples in this document, the rCell’s IP address is

192.168.2.1.

2.1 Making Requests

The RESTful interface allows users to retrieve data, add data, update data, and delete data using call methods:

GET, POST, PUT and DELETE, respectively. These methods can be set in the HTTP header, or they can be

set in the URI using the key: method. Using the URI parameter method is a useful way to execute RESTful

requests through a web browser. Additional URI parameters can be found in section 2.9 URI Parameters.

All API requests return a JSON object. The JSON response will always contain the members code and status.

The status member indicates a high-level result of the request and has two possible values: success and fail. The

code member is an HTTP response code describing the outcome of the API result. For a full list of response

code values, see section 3.2.2 Error Codes.

If an API call was successful, it may contain the member: result. This member contains data that was either

requested or data that was generated as part of the API request. If an API call was unsuccessful, the JSON

response will contain the member error. This member is a short description of the failure.

Example: Retrieving the current DHCP setting using the method URI parameter.

1GET https://192.168.2.1/api/dhcp?method=GET

3Status:HTTP /1.1 200 OK

5" code " :200 ,

6"result" :{

7"defaultGateway" :"192.168.2.1",

8"domain" :"" ,

9"enabled" :true,

10 "fixedAddresses" :[

11 {

12 " ip " :"192.168.2.15",

13 " mac " :"00 :1 A:12 :19 :3 F :60"

14 }

15 ],

16 " le aseT ime " :86 40 0 ,

17 "leases" :[

18 {

19 " ex pirat ion " :70 35 9 ,

20 " ho stN ame " :" my - pc " ,

21 " ip " :"192.168.2.103",

Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide 5

2 REQUESTS

22 " mac " :"00 :3 a:83 :10 :24 :DC "

23 }

24 ],

25 " ma xLea ses " :200 ,

26 "options" :[" dhcp - au thorita tive " ],

27 " ra nge End " :"192.168.2.254",

28 " ra ngeSt art " :"192.168.2.100",

29 " su bnetAdd ress " :"192.168.2.0",

30 " su bnetM ask " :"255.255.255.0"

31 },

32 "status" :"success"

33 }

The API allows requests to path to speciﬁc elements or groups of embedded elements. For example, if a user

only wanted to know if DHCP was enabled, they could make the request: https://[rcell ip]/api/dhcp/enabled.

Example: Path to an element within the DHCP collection.

1GET https://192.168.2.1/api/dhcp/enabled

3Status:HTTP /1.1 200 OK

5" code " :200 ,

6"result" :true,

7"status" :"success"

Accessing objects within an array can be done using the index of the desired object in the path. Some collections

support using an object’s unique identiﬁer in place of the object’s index; generally, this unique identiﬁer is a member

called name or guid. For example, suppose an rCell was conﬁgured with a GRE tunnel named MyGreTunnel, and

a user wanted to know the IP address of the remote end point of that tunnel. The user could make a RESTful

GET request to https://[rcell ip]/api/greTunnels/MyGreTunnel/remoteIp.

Example: Path to an element within an object in an array using the object’s unique identiﬁer.

1GET https://192.168.2.1/api/greTunnels/MyGreTunnel/remoteIp

3Status:HTTP /1.1 200 OK

5" code " :200 ,

6"result" :"166.184.38.73",

7"status" :"success"

2.2 Logging In

To use the API, a user must be authorized and have equal or greater privileges than the API call they are

invoking. A user can login with valid credentials by passing their username and password to the login URL (

https://192.168.2.1/api/login ) either as URI parameters or within a JSON object. The following call will

cache the token as a cookie in the user’s web browser for authorizing future calls. As an alternative to using a

browser cookie, this token can be passed as a URI parameter using the key: token. Additional URI parameters

can be found in section 2.9 URI Parameters.

Example: Login using username ’admin’ and password ’admin’.

1GET https://192.168.2.1/api/login?username=admin&password=admin

3Status:HTTP /1.1 200 OK

6Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide

2 REQUESTS

5" code " :200 ,

6"result" :{

7"address" :"192.168.2.103",

8" pe rmiss ion " :" ad min " ,

9" port " :"59486",

10 " ti mest amp " :"2 :58 :40 :389",

11 " to ke n " :"B7083A0B14C0F0BEFFBED89B99EFBC",

12 " user " :" admi n "

13 },

14 "status" :"success"

15 }

A token may timeout due to inactivity. The timeout conﬁguration is in the rCell’s Remote Access collection (

api/remoteAccess/timeoutSeconds ). There are two authorizers, one for website access and one for non-web

browser usage, such as command line utilities like wget and curl. The same user can not be logged in through the

same authorizer from more than one IP address. If a user is already logged in and attempts to login from another

IP address, a conﬂict error will be returned. A user can logout from any IP address with the proper credentials.

2.3 Logging Out

The logout call requires that the caller has equal or greater permissions than the user they are logging out. If a

user wants to logout, they can pass their authorized token in the following call:

Example:.https://192.168.2.1/api/logout?token=ABCDEF1234567890ABCDEF12345678

To logout another user (guest), a user with equal or greater permissions can use their token to authorize the call:

Example: https://192.168.2.1/api/logout?logoutUser=guest&token=ABCDEF1234567890ABCDEF12345678

Credentials can also be passed with the logout command to authorize the logout call of another user:

Example: https://192.168.2.1/api/logout?username=admin&password=admin&logoutUser=guest

2.4 Who Am I

At any point, a user can retrieve their session information using the following API call:

Example:

1GET https://192.168.2.1/api/whoami

3Status:HTTP /1.1 200 OK

5" code " :200 ,

6"result" :{

7"address" :"192.168.2.103",

8" pe rmiss ion " :" ad min " ,

9" port " :"59486",

10 " ti mest amp " :"2 :58 :40 :389",

11 " to ke n " :"B7083A0B14C0F0BEFFBED89B99EFBC",

12 " user " :" admi n "

13 },

14 "status" :"success"

15 }

Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide 7

2 REQUESTS

2.5 Passing JSON Data

Data can be sent to the rCell by passing a JSON object as the request content or by passing a JSON object in

the URI parameter: data. As an example, the following request uses a RESTful PUT call to edit the current

DHCP conﬁgurations by passing in a JSON object with the enabled member set to false

Example: To disable DHCP, send the following request:

https://192.168.2.1/apidhcp?data={"enabled":false}&method=PUT

2.6 Saving Changes

A call to save ( https://[rcell ip]/command/save ) will write current changes to the device settings. Commands

are executed using RESTful POST requests. A full list of commands can be found in section 4.1 Commands.

Example: To save the current changes, send a request to:

https://192.168.2.1/api/command/save?method=POST

2.7 Selecting a Version of an API Call

As the rCell API evolves and new features are added, backwards compatibility can be maintained by setting the

desired API version within the request. The API version can be set through the version URI parameter, or through

the URL path by subscripting the version number with the letter ’v’. If a request has only one version, this value

is ignored.

Example: To use version 1 of the API, all API requests would be made through https://[rcell ip]/api/v1/[request path]

or https://[rcell ip]/api/[request path]?version=1. If a version is not speciﬁed, the request will be executed using

the latest API version.

2.8 Element Descriptions

The API provides documentation on collections and elements through https://[rcell ip]/api/help. For a description

of an element or group of elements, use the path to retrieve the data and prepend help to the collection component.

For example, if a user wanted information on the DHCP element enabled ( https://[rcell ip]/api/dhcp/enabled

), they could submit a RESTful GET request to https://[rcell ip]/api/help/dhcp/enabled.

Example: Retrieving a description of the DHCP member enabled.

1GET https://192.168.2.1/api/help/dhcp/enabled

3Status:HTTP /1.1 200 OK

5" code " :200 ,

6"result" :{

7"dhcp_enabled" :" en ab le or d is abl e DHCP ser ver ( de fa ult :true) :BOOL"

8},

9"status" :"success"

10 }

The API also provides a separate set of help descriptions that are used by the rCell website for context-sensitive

help-on-hover content. The path to each description follows the menu and category embedding of the rCell

website.

8Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide

2 REQUESTS

Example: Retrieving a more human-readable description of the DHCP member enabled.

1GET https://192.168.2.1/api/help/Setup/DHCP/Settings/Enabled

3Status:HTTP /1.1 200 OK

5" code " :200 ,

6"result" :{

7"Setup_DHCP_Settings_Enabled" :" Che ck to use a DHCP s erv er on ne tw ork "

8},

9"status" :"success"

10 }

2.9 URI Parameters

URI parameters are reserved keys that are used to modify the functionality of API calls, override HTTP header

values, and bundle multiple API requests together. Below is a list of available URI keys and descriptions of their

functionality.

URI Key Description

ﬁelds Applies a RESTful action to multiple collections/elements. Each request path is separated by a comma. Requested

data within a ﬁeld is returned using the path by replacing ’/’ characters with ’ ’ characters.

Example:

1GET https://192.168.2.1/api?fields=lan/ip,serial/client/enabled&method=GET

3Status:HTTP /1.1 200 OK

5" code " :200 ,

6"result" :{

7"lan_ip" :"192.168.2.1",

8"serial_client_enabled" :false

9},

10 "status" :"success"

11 }

method Allows passing RESTful action (GET, PUT, POST, & DELETE) in URI. This overrides the HTTP header method.

See section 2.1

apply Allows the request to be applied at the given timestamp without restarting. Currently, only apply=now is

supported.

token Authorized Login Token. This can be passed to authorize an API call. A token is returned upon a successful

inactivity Allows requests to be made without bumping the user’s token expiration date. This is useful for automated polling

loops that still want to allow a user to timeout due to inactivity (inactivity=true)

session Reserved for internal use. This member will be overwritten.

data Allows passing a JSON Object in the URI.

default This option will retrieve the factory defaults of a collection when using a RESTful GET request, and set a collection

to its factory defaults when using a RESTful PUT request. (default=true)

version Sets the API version to use during the request. See section 2.7

username User’s login name. Used for logging into the API. See section 2.2

password User’s login password. Used for logging into the API. See section 2.2

logoutUser User to be logged out. Only used on api/logout request. See section 2.3

Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide 9

3 RESPONSES

3 Responses

All API requests return a JSON object. The JSON response will always contain the members code and status.

The status member indicates a high-level result of the request and has two possible values: success and fail. The

code member is a HTTP response code describing the outcome of the API result. Certain actions or events in

the API may result in a URL redirect, such as trying to access API methods when a user is not logged in. In these

situations, the JSON response may contain the member referrer.

3.1 Success

In the event of a successful request a success message will be returned with the member status set to success

and code set to 200. If data is sent in the response it will be found in the result ﬁeld.

3.1.1 Success response format

1Status:HTTP /1.1 200 OK

3" code " :200 ,

4"status":"success",

5"result":{[JSON Obj ect or Arr ay ]}

3.2 Error

An error response will always contain the members: code,status, and error. If an error is encountered during a

request, the API will halt processing and return an error message. This means that a request with multiple errors

will receive a response containing error information on only the ﬁrst error that the API ﬁnds during the processing

of that request.

3.2.1 Error response format

1Status:HTTP/1.1 [Er ro r Cod e ] [ Er ror M es sag e ]

3" code " :[Err or Co de ],

4"status":" fai l ",

5" er ro r ":"[Error Me ss age ]"

10 Multi-Tech Systems, Inc. MultiConnect R

rCell API Developer Guide

Autres manuels pour MultiConnect rCell MTR-H5

Ce manuel convient aux modèles suivants

Table des matières

Autres manuels Multitech Routeur réseau

Multitech

Multitech MultiFRAD FR221 Manuel utilisateur

Multitech

Multitech MultiConnect rCell 100 Series Manuel utilisateur

Multitech

Multitech rCell 500 Series Manuel utilisateur

Multitech

Multitech RouteFinder RF550VPN Manuel utilisateur

Multitech

Multitech MTR-L4G1 Instructions d'installation

Multitech

Multitech RouteFinder MTASR2-201 Manuel utilisateur

Multitech

Multitech RouteFinder MTASR1-100 Manuel utilisateur

Multitech

Multitech RouteFinder RF560VPN Manuel utilisateur

Multitech

Multitech MultiConnect rCell 100 Series Feuille d'instructions

Multitech

Multitech RouteFinder RF825-C-Nx Manuel utilisateur

Multitech

Multitech Embedded Modem Manuel utilisateur

Multitech

Multitech MultiFrad FR3100 Manuel utilisateur

Multitech

Multitech MultiConnect rCell MTR-H6 Manuel utilisateur

Multitech

Multitech MultiFrad FR3060 Manuel utilisateur

Multitech

Multitech MultiConnect rCell 100 Series Manuel utilisateur

Multitech

Multitech MultiConnect rCell 100 Series Manuel utilisateur

Multitech

Multitech MultiConnect rCell 100 Series Instructions d'installation

Multitech

Multitech MultiConnect rCell 100 Series Manuel utilisateur

Multitech

Multitech MultiConnect rCell 100 Series Manuel utilisateur

Multitech

Multitech RouteFinder RF850 Manuel utilisateur

Multitech

Multitech RouteFinder MTASR3 Manuel utilisateur

Multitech

Multitech MultiFRAD FR220 Manuel utilisateur

Multitech

Multitech MultiConnect rCell MTR-H5 Manuel utilisateur

Multitech

Multitech MultiFRAD FR2201 Manuel utilisateur

Manuels Routeur réseau populaires d'autres marques

Allnet

Allnet ALL0333AU Manuel utilisateur

HomeSeer

HomeSeer HT-SEL Manuel utilisateur

Sercomm

Sercomm Genesis OC3505D Manuel utilisateur

Billion

Billion BIPAC 5102 Series Manuel utilisateur

TP-Link

TP-Link TD-8817 Manuel utilisateur

Motorola

Motorola MR1900 Manuel utilisateur

Digi

Digi IX14 Manuel utilisateur

Cisco

Cisco NCS 540 Manuel

XAVi

XAVi X8821e Manuel utilisateur

BEC

BEC 6200WZL Manuel utilisateur

MikroTik

MikroTik hAP ac3 Series Manuel utilisateur

Korenix

Korenix JetNet 5428G Series Manuel utilisateur

NETGEAR

NETGEAR FS526T - Switch Manuel utilisateur

Korenix

Korenix JetNet 5710G Series Manuel utilisateur

Automated Logic

Automated Logic ZN551 Manuel du propriétaire

Cisco

Cisco ASR 1000 Series Manuel de l'opérateur

EnGenius

EnGenius ESR-9710 Manuel utilisateur

Cisco

Cisco 805 Series Instructions d'utilisation et de sécurité