This section describes the pre-REST versions of the web service interface. These are largely compatible with the REST web services, but new solutions should base their designs around the REST interface.
You can call any Metrici service remotely through the web service interface.
There are two forms of the web service interface, one in which parameters are passed in the URL (or as POST parameters), and one in which the entire XML request is passed in the http request body.
URL-based web service call
The URL-based web services are available using URL /service/ServiceName. For example, the GetNode service is available at https://www.metrici.com/service/GetNode.
Parameters for the service call are passed using the same "flat XML" conventions as the Service Message Writer. In most cases, you only need to pass top-level XML elements which equate directly to URL parameters.
For example, the following returns details of the system.NODE_NAME node:
https://www.metrici.com/service/GetNode?nodeVersionReference=system.NODE_NAME
Parameters can be passed in the URL or as POST parameters using form data or multipart/form data conventions. If the POST body if of a different type, the entire body will be available in the body parameter.
XML body web service call
For more complicated service calls, use URL /service and pass the entire XML request in the body of a POST request.
For example, on Linux you can use the curl utility, as in this example which runs the request in service.xml.
curl -X POST -H "Content-Type:application/xml" -L https://www.metrici.com/service -d "@service.xml"
You must set content type to be application/XML, and must set the -L option to follow redirects. The quotes around the @file specification are required when calling curl in Windows.
Executing nodes
You can execute scripts on nodes using the ExecuteScript service, and passing the node version reference as a parameter.
https://www.metrici.com/service/ExecuteScript?nodeVersionReference=your.node.reference
You can use the service or servicejson path.
Alternatively, you can use a method of service (or servicejson) to achieve the same, which may provide a more meaningful URL. For example, the following URL is equivalent to the one above.
https://www.metrici.com/your/node/reference?method=service
This is much the same as ?method=execute, except that the response is returned to the caller as is, and is not interpreted as a page.
Web service credentials
If you call a Metrici web service from a browser and the browser session has already signed in to Metrici, then your credentials will automatically be added to each web service call.
In other cases, you need to pass credentials with each call, with a userLogonReference/password pair or a session token.
If you are passing XML in the body of a web service call, you must pass the credentials in the body.
If you are using a URL-based web service call, or passing parameters using formdata or multipart-formdata then either you can pass the credentials as parameter or can pass them using preemptive basic authentication. In preemptive basic authentication, a hash of the user name and password is sent in the Authorization header. You can use either:
- A user name of the userLogonReference and password of the password.
- A user name of "session" and a password of sessionToken:clientSessionToken. If you have a single-use session token, clientSessionToken is optional, but the session token will only work for a single call.
If you have not signed in to Metrici, and you are on a browser or some other web client that will use session cookies, you can mimic the sign in and sign out processes using the /service/SignOn web service, which takes user credentials, and the /service/SignOff web service. These will create a server-side session and apply credentials to all subsequent calls.
When you are passing credentials in web service calls, make sure to use https:// not http://. From a browser script on a Metrici page, you can use the global variable rootPath to find the correct URL (e.g. use rootPath + "service" for https://www.metrici.com/service).