Authentication is the mechanism of associating an incoming request with an API key. The PC*MILER REST service requires an API key to access the service. Go here if you need a key.
An API Key is a piece of code assigned to a specific user or account that is used whenever that entity makes a call to an API. This key is a long string of generated characters.
An API Key has these properties:
A token, in the form of a relatively long random string (e.g. 32 characters)
An identifier, for storage and unique identification
Transmitted with the request
Known to the client
Can be validated by the server
Unique to a device or software
Bound to a user or account
A client device will store the token. In a way this is like a password, but there is no need for restricting this to human memory capabilities. The token is transmitted with every request so the request can always be authenticated.
The API key is used either in the URL or in the HTTP request header to validate a user’s request. If the client making the API request has an invalid API key, then the key will fail to authenticate. The API key is most important to the request. You need this to generate a successful login and send it with the request. If the user is successfully logged in, a valid response will be returned from the server.
We support HTTP and HTTPS, but recommend sending your request over HTTPS. If you’re not using SSL, then your authentication protocol will never be secure.
Requests
A typical REST action consists of sending an HTTP request to the PC*MILER API Server and waiting for the response. Like any HTTP request, a REST request to PC*MILER API Server contains a request method, a URI, request headers, and a query string or request body. The response contains an HTTP status code, response headers, and a response body.
The REST API is used to expose the Web Services of our PC*MILER application by using simple HTTP requests, which includes the following:
POST method for creating a new Object on server
GET method for getting single/list of Objects from server
PUT method to update an Object on server
DELETE method for deleting an Object from server
Request Properties
HOST
Mandatory.
The Host header defines PC*MILER REST API server (where to connect).
Value: pcmiler.alk.com
Example: Host: pcmiler.alk.com
API KEY
Mandatory.
API Key will be used to fully determine privileges and visibility for the request within PCMiler platform.
Example:
(Request Header)
Authorization: ed5620c5013d782fe2eeaf9fd03b7fc0a42fafb06f0608b58d5
Or
(in URL)
&authToken= ed5620c5013d782fe2eeaf9fd03b7fc0a42fafb06f0608b58d5
CONTENT-TYPE
Defines expected request MIME type
application/json: PC*MILER will render the response in JSON format following the current REST API specifications
Sample Requests
GET
URL based authentication:
http://pcmiler.alk.com/APIs/REST/v1.0/Service.svc/locations?coords=-85.9747,37.8928&authToken=YourAPIKeyHere
Java Header Based GET Authentication
Query = "coords=-85.9747,37.8928";
String nospac = Query.replace(" ", "%20");
address = "http://pcmiler.alk.com/apis/rest/v1.0/Service.svc/locations?";
urlFormatted = address + nospac;
url = new URL(urlFormatted);
connection = (HttpURLConnection) url.openConnection();
connection.setRequestProperty("Authorization", apiKeyVal);
connection.setUseCaches(false);
connection.setDoOutput(true);
connection.setReadTimeout(15 * 1000);
connection.connect();
builder = new StringBuilder();
String type = connection.getContentType();
if (type == null) {
return;
}C# Header Based Get Authentication
string resource = "locations";
string queryString = "?coords=-85.9747,37.8928";
Uri requestUri = new Uri(baseURL + resource + queryString);
HttpWebRequest req = WebRequest.Create(requestUri) as HttpWebRequest;
req.Headers["Authorization"] = apiKey.Text;
req.ContentType = "application/json";
try
{
using (HttpWebResponse response = (HttpWebResponse)req.GetResponse())
{
using (StreamReader sr = new StreamReader(response.GetResponseStream()))
{
txtResponse.Text = sr.ReadToEnd();
}
}
}JavaScript Header Based GET Authentication
<html>
<head>
<script type="text/javascript">
reqhttp = new XMLHttpRequest();
var url = "http://pcmiler.alk.com/APIs/REST/v1.0/Service.svc/";
var resource = "locations"
var queryString = "?coords=-85.9747,37.8928";
url = (url + resource + queryString);
reqhttp.open("GET", url, true);
reqhttp.onreadystatechange = ProcessRequest;
function ProcessRequest() {
if (reqhttp.readyState == 4 && reqhttp.status == 200) {
TextArea1.value = "Request: " + url + "\n\n";
TextArea1.value = TextArea1.value + "Response: " + reqhttp.responseText;
}
}
reqhttp.setRequestHeader("Content-type", "application/json");
reqhttp.setRequestHeader("Authorization", apiKeyVal);
reqhttp.responseType = "application/json";
reqhttp.send();
</script>
<style type="text/css">
#TextArea1
{
width: 693px;
height: 167px;
}
</style>
</head>
<body>
<div>
<textarea id="TextArea1" name="S1"></textarea></div>
</body>
</html>POST
JAVA POST Snippet
address = ("http://pcmiler.alk.com/APIs/REST/v1.0/Service.svc/mapRoutes?dataset=Current");
url = new URL(address);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
apiKeyVal = apiKey.getText();
conn.setRequestProperty("Authorization", apiKeyVal);
queryStr.setText("{ MyPostQuery }");
String input = queryStr.getText();
OutputStream os = conn.getOutputStream();
os.write(input.getBytes());
os.flush();
if (conn.getResponseCode() != 200)
if (conn.getResponseCode() != HttpURLConnection.HTTP_CREATED) {
throw new RuntimeException("Failed : HTTP error code : "
+ conn.getResponseCode());
}
String type = conn.getContentType();
if (type == null) {
return;
}C# POST Snippet
var request = (HttpWebRequest)WebRequest.Create("http://pcmiler.alk.com/APIs/REST/v1.0/Service.svc/mapRoutes?dataset=Current");
var postData = "{ MyPostQuery }";
var data = Encoding.ASCII.GetBytes(postData);
request.Headers.Add("Authorization", apiKey.Text);
request.Method = "POST";
request.ContentType = "application/json";
request.ContentLength = data.Length;
using (var stream = request.GetRequestStream())
{
stream.Write(data, 0, data.Length);
}
var response = (HttpWebResponse)request.GetResponse();
if (response.ContentType.StartsWith("image"))
{
Image mapImage = Image.FromStream(response.GetResponseStream());
pictureMap.Size = mapImage.Size;
mapImage1 = mapImage;
pictureMap.Visible = true;
pictureMap.Image = mapImage;
txtResponse.Visible = false;
}JavaScript POST Snippet
<html>
<head>
<script>
reqhttp = new XMLHttpRequest();
var url = "http://pcmiler.alk.com/APIs/REST/v1.0/Service.svc/mapRoutes?dataset=Current";
reqhttp.open("POST", url, true);
reqhttp.setRequestHeader("Content-type", "application/json");
reqhttp.setRequestHeader("Authorization", apikey);
reqhttp.responseType = "arraybuffer";
reqhttp.onreadystatechange = function () { //Call a function when the state changes.
if (reqhttp.readyState == 4 &amp;&amp; reqhttp.status == 200) {
var res = reqhttp.response;
if (res) {
var uInt8Array = new Uint8Array(res);
var i = uInt8Array.length;
var binaryString = new Array(i);
while (i--) {
binaryString[i] = String.fromCharCode(uInt8Array[i]);
}
var data = binaryString.join('');
var base64 = window.btoa(data);
document.getElementById("myImage").src = "data:image/png;base64," + base64;
}
}
}
var parameters = "{ MyPostQuery}";
doFunction();
function doFunction() {
reqhttp.send(parameters);
}
</script>
</head>
<body>
<div>
<img id="myImage">
</div>
</body>
</html>This sample may use features that are only available in our Premium Web Services.