(Update with the copy of version: 8.5.2DRAFT) |
(Update with the copy of version: 8.5.2DRAFT) |
||
| Line 2: | Line 2: | ||
__TOC__ | __TOC__ | ||
| − | You can use the Web Services API to send and receive {{#Widget:ExtLink|link=http://www.json.org|displaytext=JSON}}-based data over HTTP. We are using {{#Widget:ExtLink|link=http://curl.haxx.se|displaytext=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 | + | You can use the Web Services API to send and receive {{#Widget:ExtLink|link=http://www.json.org|displaytext=JSON}}-based data over HTTP. We are using {{#Widget:ExtLink|link=http://curl.haxx.se|displaytext=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. | 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. | ||
| Line 72: | Line 71: | ||
</source> | </source> | ||
| − | ====REST | + | ====REST client==== |
Instead of writing a client application to test your API calls, you can use a REST client embedded in your web browser. | Instead of writing a client application to test your API calls, you can use a REST client embedded in your web browser. | ||
<div class="cloud-left"> | <div class="cloud-left"> | ||
| Line 83: | Line 82: | ||
</div> | </div> | ||
| − | ====Web | + | ====Web browser==== |
This call is the only REST API call you can make in a web browser because it doesn't require authentication. All you need to do is navigate to the following URL: <tt><nowiki>http://WS_Server:WS_Port/api/v2/diagnostics/version</nowiki></tt> | This call is the only REST API call you can make in a web browser because it doesn't require authentication. All you need to do is navigate to the following URL: <tt><nowiki>http://WS_Server:WS_Port/api/v2/diagnostics/version</nowiki></tt> | ||
| Line 95: | Line 94: | ||
== Authentication == | == Authentication == | ||
| − | + | The following request asks for information about user <tt>ksippo</tt>. Like most Web Services requests, this one requires authentication. cURL allows us to specify the user name and password by using the format <tt>-u '''username:password'''</tt>. | |
| − | The following request asks for information about user <tt>ksippo</tt>. Like most Web Services requests, this one | ||
The user mentioned in the following request does not have a password, so we have left the password field empty: | The user mentioned in the following request does not have a password, so we have left the password field empty: | ||
| Line 123: | Line 121: | ||
</source> | </source> | ||
| − | == Sending | + | == 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, <tt>ksippo</tt>. | |
| − | Sending data is a bit more complex. We | ||
Finally, the following request uses the cURL data parameter, <tt>-d</tt>, to carry the JSON payload, which lets the server know that we want to set ksippo's status to <tt>NotReady</tt>. | Finally, the following request uses the cURL data parameter, <tt>-d</tt>, to carry the JSON payload, which lets the server know that we want to set ksippo's status to <tt>NotReady</tt>. | ||
| Line 139: | Line 136: | ||
</source> | </source> | ||
| − | === Filtering | + | === 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 [[Documentation:HTCC:API:Subresources|Subresources]] topic. | 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 [[Documentation:HTCC:API:Subresources|Subresources]] topic. | ||
| − | == What's | + | == What's next? == |
| − | |||
Now that we have an idea of how to send requests, let's take a look at how to [[InterpretingaResponse|interpret responses]] from the Web Services server. | Now that we have an idea of how to send requests, let's take a look at how to [[InterpretingaResponse|interpret responses]] from the Web Services server. | ||
[[Category:V:HTCC:8.5.2]] | [[Category:V:HTCC:8.5.2]] | ||
Revision as of 18:22, March 25, 2016
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.