Making a Request
Contents
You can use the Web Services API to send and receive JSON-based data over HTTP. We are using cURL, which is command-line based, so you will want to open your favorite command line, terminal, or shell program, after making sure that it supports cURL. And of course, you should plug in the URL for your own Web Services server, as well as other site-specific information, when you issue the following cURL commands.
A simple request
As you might expect, your HTTP requests require a URL that contains the address of your server and the path to your Web Services API library.
The rest of the URL indicates what kind of operation you would like to perform. Web Services operations are asynchronous. When a request returns "statusCode":0, this doesn't indicate a successful change of state — only that the request was successfully sent to T-Server.
In most cases, when you send a request you will also need to provide authentication. But you don't need authentication to ask for your current version of Web Services. To do this, type in the following cURL command:
curl http://000.111.222.333/api/v2/diagnostics/versionThe above request will return something like this:
{"statusCode":0,"version":"8.5.200.50"}[+] Click here to see other ways you can retrieve the Web Services version.
Authentication
The following request asks for information about user ksippo. Like most Web Services requests, this one requires authentication. cURL allows us to specify the user name and password by using the format -u username:password.
The user mentioned in the following request does not have a password, so we have left the password field empty:
curl -u ksippo: http://000.111.222.333/api/v2/meThe response from the Web Services server should look something like this:
{
"statusCode":0,
"user":{
"id":"63630bbebf4840d7a0bffd6312bc29ff",
"userName":"ksippo",
"firstName":"Kristi",
"lastName":"Sippola",
"roles":["ROLE_AGENT"],
"enabled":true,
"changePasswordOnFirstLogin":false,
"uri":"http://127.0.0.1/cloud-web/api/v2/users/63630bbebf4840d7a0bffd6312bc29ff",
"path":"/users/63630bbebf4840d7a0bffd6312bc29ff"
}
}Sending data
Sending data is a bit more complex. We use a POST request and indicate to cURL that we are sending data in JSON format. We also use a URL that tells the Web Services server to carry out an operation for the current user, ksippo.
Finally, the following request uses the cURL data parameter, -d, to carry the JSON payload, which lets the server know that we want to set ksippo's status to NotReady.
curl -X POST -H "Content-Type: application/json" -d '{"operationName":"NotReady"}' -u ksippo: http://000.111.222.333/api/v2/me/channels/voiceIf we did everything right, we will get confirmation from the server by way of a status code of 0:
{"statusCode":0}Filtering a request
You may also want to get specific information associated with an agent or other user, such as a list of their skills or devices. To do this, you can filter your request, as shown in the Subresources topic.
What's next?
Now that we have an idea of how to send requests, let's take a look at how to interpret responses from the Web Services server.