Rogers Catalyst

 
null
28
Feb
2011
 

Be RESTful with curl PART-1

Posted by Vishal
 

About this Blog Post

As a Rogers Catalyst newbie I will be doing some serious hands on platform APIs to develop a deep expertise on the APIs as well as broad know-how around how applications and services are developed with the Rogers Catalyst platform. “Be RESTful with curl” series of blog posts are my chronicles of this learning process. This will be particularly useful for you if you are taking a first stab at the Rogers Catalyst APIs or if you want to learn to use curl to interact with RESTful web services. Part 1 of this series will deal with Location and Privacy APIs

Rogers Catalyst Location Service

Location web-service will allow your app to retrieve the location (latitude/longitude) of a Rogers or Fido mobile phone. The location services leverages our network infrastructure to identify the location of the handset. The cool thing about this technique is that it will allow you to retrieve location of “any” device on our network irrespective of make, model or mobile operating system.

Rogers Catalyst Privacy Service

To be able to retrieve the location of a mobile phone, you will need to get mobile phone owner’s permission to allow your application to retrieve the location of their mobile phone. The privacy web service provides a mechanism for our customers to “allow” or “deny” your app to retrieve the location of their mobile phone. 

curl

curl is a command-line tool for transferring data using various protocols including HTTP. In this tutorial I am going to show how curl can be used to

  1. Interact with RESTful web services with GET and PUT verbs over a secure connection
  2. Use HTTP basic access authentication with base64 encoding
  3. URL encode query string data for HTTP GET method
  4. URL encode data for HTTP POST methods             

RESTful Web Services

Wikipedia defines a RESTful web Service as a simple web service implemented using HTTP and the principles of REST. It is a collection of resources, with three defined aspects:

1 - The base URI for the web service.

This is where you will find the web service if you want to interact with it. W3C Working Group has coined the term “endpoint” for this URI (see http://www.w3.org/TR/ws-gloss/). For example the “endpoint” for Rogers Catalyst location service used in this tutorial is:

https://www.rogerscatalyst.com/TerminalLocationService/REST_v0_91/location

2 - The media or content type

This is often JSON, XML or YAML. For Rogers Catalyst web services this is XML.

3 - The set of operations

The set of operations supported by the web service using HTTP methods e.g., POST, GET, PUT or DELETE. For example Rogers Catalyst Location RESTful service supports HTTP GET and Privacy service supports PUT verbs respectively. 

Get Set Up 

Follow three simple steps to sign-up for a free Rogers Catalyst Account at http://www.rogerscatalyst.com/

Step 1 - Register 

Click on Register Now and follow on screen instructions to create an account. You will receive confirmation e-mail after the sign-up process is complete. Click the link in the email and complete the validation process.

Step 2 - Create a Developer Profile

Log in to your Rogers Catalyst account and click on Dashboard. Click on  “Create a Developer” and follow on-screen instructions to create a developer profile

Step 3 - Create a Project

On you Dashboard, click the name of your Developer Profile. On the Developer Profile page, click the “Create Project” button. Follow on screen instructions to create a Rogers Catalyst project.

Detailed instructions on setting up a free Rogers Catalyst Account can be found  here 

A Word About Projects

You can think of your project as your app. Some important attributes of a project are: 

Project Name

For this tutorial I have used  “Resting With Curl" for Project Name. Choosing the right project name is important becasue customers will identify your app with this project name. For example when you invoke the privacy web-service, the mobile phone user will be notified about your application’s intent to retrieve the location of their mobile phone. This notification will be sent out as a SMS text message. This Project Name will appear in the SMS text.

Project Credentials

Project User name and Password are the credentials that will authenticate the API calls from your application with HTTP basic authentication.

Endpoints

This is a list of http URIs for all Rogers Catalyst Web Services that have been provisioned for this project.

Location web-service endpoint used in this tutorial is:  

https://www.rogerscatalyst.com/TerminalLocationService/REST_v0_91/location

Privacy web-service endpoint used in this tutorial is:

https://www.rogerscatalyst.com/PrivacyService/rest

Test Device or CTN

These are the Rogers or Fido mobile phone numbers you wish to use with this project. This mobile number can also be accessed or configured as a Customer Telephone Number (CTN) in the whitelist section of your project.

Set Up Your Environment

I am using Lucid Lynx (Ubuntu 10.4 LTS Desktop) for my development environment, although this tutorial will work on Snow Leopard or any *nix distribution with latest version of curl. To install curl on Lucid Lynx use apt-get 

sudo apt-get install curl 

Run curl --version using Terminal, it should show something similar to:

curl 7.19.7 (i486-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15

Protocols: tftp ftp telnet dict ldap ldaps http file https ftps

Features: GSS-Negotiate IDN IPv6 Largefile NTLM SSL libz 

GET Location of a Mobile Phone

Let’s do a HTTP GET on the Rogers Catalyst location endpoint. Open the Terminal and run the following command:

curl  --user your-project-user-name:your-project-password  \

       --get     \

       --data-urlencode "address=tel:+16472411234" \

       --data-urlencode "accuracy=1000" \

       --include "https://www.rogerscatalyst.com/TerminalLocationService/REST_v0_91/location"

Let’s take a look at the curl parameters

1. The “--user” option tells curl to send the HTTP request with basic authentication. The username and password strings should be separated by a colon (“:”) character. The whole string will be base64 encoded by curl as required by RFC 2617. 

2. The “--data-urlencode” option provides a mechanism to send query string parameters in a HTTP GET request or to send form data in a POST request. The data will be url encoded to ensure that no reserved or special characters are transmitted over the wire. In the example above we are sending "address" and "accuracy" as query string parameters.

3. The “--get” option tells curl to send the “--data-urlencode” data with a HTTP GET. If this option is omitted, curl with POST the “--data-urlencode” as form data.  

4. The “include” option tells curl to include HTTP headers in the output

You should see the following response:

Response:

HTTP/1.1 403 Forbidden

Date: Sat, 12 Feb 2011 20:32:30 GMT

Server: Jetty(6.1.x)

Content-Type: application/xml

Content-Length: 152

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<error> A policy error occurred. Error code is POL-010: Subscriber target not authorized.</error>

Policy Error POL-010

A policy error POL-010 implies that the user has not authorized your application to retrieve location information. In order to successfully obtain mobile location, your application must be authorized by the mobile phone user. This is achieved with the privacy RESTful web-service. When you invoke a privacy request, the mobile phone user will be notified of your application’s intent to retrieve their location and prompted for their response via a SMS message. The user can respond ALLOW or DENY either permitting or blocking access to their location information.

Privacy web-service with HTTP POST

Let's invoke the Privacy web-service, which is done as a HTTP POST method

curl    --user your-project-user-name:your-project-password \

        --data-urlencode "address=tel:+16472411234" \

        --data-urlencode "callbackUrl=http://www.w3.org/2005/08/addressing/none" \

        --include "https://www.rogerscatalyst.com/PrivacyService/rest"

Note that without "--get" option curl will POST the “--data-urlencode” data as form data. In this example we are sending address i.e. the mobile phone number and callback url as form data with Content-Type header set to "application/x-www-form-urlencoded". The callback url tells Rogers Catalyst where to send a notification once a SMS response has been received by the user. For this example we are not going to use the callback notificaton so callback URL is not relevant. 

You should see the following response:

Response:

HTTP/1.1 200 OK

Date: Sat, 12 Feb 2011 20:53:34 GMT

Server: Jetty(6.1.x)

Content-Type: application/xml

Content-Length: 90

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><PrivacyResponse status="PENDING"/>

Advice of Privacy (AOP)

At this point you will see an SMS from 6001 with the following text on your test mobile phone. This is SMS text represents an advice of privacy to the mobile phone user.

“<Your Application Name > is requesting access to your location. Please reply with ALLOW to enable, DENY to disallow or STOP to cancel all local authorizations”

Use your mobile phone to reply with allow or ALLOW (its not case sensitive)

Let’s do a HTTP POST to the privacy resource again 

curl  --user your-project-user-name:your-project-password \

       --data-urlencode "address=tel:+16472411234" \

       --data-urlencode "callbackUrl=http://www.w3.org/2005/08/addressing/none" \

       --include "https://www.rogerscatalyst.com/PrivacyService/rest"

You should see the following response:

Response:

HTTP/1.1 200 OK

Date: Sat, 12 Feb 2011 21:03:48 GMT

Server: Jetty(6.1.x)

Content-Type: application/xml

Content-Length: 90

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><PrivacyResponse status="ALLOWED"/>

PrivacyResponse status="ALLOWED"  implies that your application has been allowed access to the mobile phone’s location data.

Putting It Together 

Let's send the location request again

curl  --user your-project-user-name:your-project-password \

       --get     \

       --data-urlencode "address=tel:+16472411234" \

       --data-urlencode "accuracy=1000" \

       --include "https://www.rogerscatalyst.com/TerminalLocationService/REST_v0_91/location"

You should see a 200 OK response with location data in the xml payload

Response:

HTTP/1.1 200 OK

Date: Fri, 25 Feb 2011 13:06:16 GMT

Server: Jetty(6.1.x)

Content-Type: application/xml

Content-Length: 266

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<GetLocationResponse version="0.91">

<location timestamp="Mon, 28 Feb 2011 19:08:21 EST" longitude="-79.37923" latitude="43.670162" altitude="0.0" address="tel:+16472419263" accuracy="103"/>

</GetLocationResponse>

Rogers Catalyst Command Line Utility

I have developed a command line utility that uses curl to invoke Privacy, Location, SMS and other Rogers Catalyst RESTful web services. The utility is licensed under the Apache 2.0 license, so you can use, modify and re-distribute the code with the appropriate attribution. Download the command line utilty from github here 

See Also

1. Rogers Catalyst Resources

2. Rogers Catalyst Command Line Utility 

3. Manual - curl usage explained

4. Percent Encoding ,  Basic Access Authentication & RFC 2617

 
 

Comments

Please login or register to comment on this post.

Twitter

Off The Blog