Developing Custom VersionOne Apps 101 Series Guide

In the last article, Test Drive the VersionOne Feature Requestor Sample Custom App, we took a tour of the VersionOne Feature Requestor Sample Custom App, a usable example app that makes it easier for you or your customers to provide “Feature Requests” that get saved inside of your VersionOne instance.

The Feature Requestor app serves as a perfect diving board for us to now understand how web apps work, starting with HTTP, the Hypertext Transfer Protocol.

In this article, you will

  • Learn about why the web was created in the first place
  • Understand how the HTTP protocoal is structured and what it does for you and your web browser
  • Experiment with several HTTP requests and HTTP responses in your browser

After understanding the basics of HTTP, you’ll be ready to learn more about REST (REpresentational State Transfer), REST-based Application Programming Interfaces (APIs), and how to write your own custom VersionOne apps with the VersionOne RESTful APIs.

What you’ll need

  • We’ll use Google Chrome because of its great Developer Tools, but other browsers have these tools as well. If you use another, you’ll have to fiddle with their developer tools a bit.
  • A favorite search engine. Mine is Google.

In the beginning

In the beginning was Tim Berners-Lee, and by the beginning I mean 1989. Tim worked at CERN, and wanted a way to GET existing documents and POST new documents on the internet. He wanted this so collaboration between between CERN and other scientific organizations could become easier and faster.

The concept of hypertext already existed (because there was a beginning before the beginning, you see). Thus, as he recalls:

I just had to take the hypertext idea and connect it to the Transmission Control Protocol and domain name system ideas and—ta-da!—the World Wide Web … Creating the web was really an act of desperation, because the situation without it was very difficult when I was working at CERN later. Most of the technology involved in the web, like the hypertext, like the Internet, multifont text objects, had all been designed already. I just had to put them together. It was a step of generalising, going to a higher level of abstraction, thinking about all the documentation systems out there as being possibly part of a larger imaginary documentation system.

The simplest thing that could possibly work: do ya GET it?

Tim and his team at CERN certainly hit on that age old agile idea captured in the oft-heard phrase , “Do the simplest thing that could possibly work”.

The first version of the protocol had only one method, namely GET, which would request a page from a server. The response from the server was always an HTML page. — HTTP article on Wikipedia

GET a document (or resource) from the web

The GET method Tim mentioned above is still in operation today. Holy cow is it still in operation today! In fact, it’s most certainly the most used HTTP operation, although with the number of Facebook updates and tweeting tweeters out there, POST may catch up, but we’ll discuss that in a moment.

For now, do this:

Open a new browser tab and type type http://www.google.com into the address bar, then hit enter.

What’s happens next is:

  • Your browser creates and sends an HTTP request to the Google web server using the GET HTTP method.
  • Google processes the request, then sends an HTTP response back to your browser,
  • Your browser renders the result as HTML, with a nice little search box in the middle.

Aside: You might take it for granted now, but when Google came out, it was a “radical” idea that all they had was a single text box for you to type what you want into it. You see, most search engines back then wanted to throw tons of content at you, hoping you’d click and read what they wanted you to read. But, just like Tim’s original, single GET method for HTTP, it’s amazing how simple designs end up winning in the end, isn’t it? In fact, the “simplest thing” link above is to an interview with Ward Cunningham, the inventor of the Wiki technology that I’m sure you know and love and depend on too.

POST a document (or resource) to the web

Of course, GET was not enough. In order for Tim and his colleagues to POST new documents that others could GET, they needed a new HTTP method.

They called it POST, duh

Naming things for what they mean and do, what a novel idea!

It used to be the case that a lot of search engines would use the POST method when you searched for something. After all, you were filling out a form with some data, and then sending that to the server. But, as we’ll see in the next article about REST, this is not really necessary. So, Google and other search engines these days typically use GET even when you enter data into the search box and ht enter.

So, this time, navigate to http://www.pastebin.com and type in something to the form under the New Paste header, then scroll down and hit the Submit button.

Now what happens is:

  • Your browser creates an HTTP request, like before, but now uses the POST HTTP method and sends it off to Pastebin along with the text you typed in as a request body
  • Pastebin’s server reads the request body and saves a copy of it somewhere, and creates a brand new URL for you and the rest of the world to access the data at, then it redirects your browser to that new page.
  • If you click one of those links, your browser then issues a new HTTP request with the aforementioned GET HTTP method.
  • It’s that simple!

Peeling the onion

Don’t worry, this won’t make you cry, but it might make your eyes sting a bit.

Look at this slightly more technical description of HTTP from Wikipedia:

HTTP functions as a request-response protocol in the client-server computing model. A web browser, for example, may be the client and an application running on a computer hosting a web site may be the server. The client submits an HTTP request message to the server. The server, which provides resources such as HTML files and other content, or performs other functions on behalf of the client, returns a response message to the client. The response contains completion status information about the request and may also contain requested content in its message body.

HTTP verbs tell remote web servers how to act

We just saw HTTP GET and HTTP POST in action. GET is used any time you type a URL into your address bar and hit enter, and POST is used when you enter data into submission form like Pastebin. POST is also used when you share a new Facebook status or send a new Tweet to your followers.

But, there are other verbs in HTTP. We won’t really need to worry about those others in this tutorial, and you won’t really need to worry about them when using the VersionOne APIs, but for your reference and curiosity, here’s an excerpt from Wikipedia:

HTTP defines methods (sometimes referred to as verbs) to indicate the desired action to be performed on the identified resource. What this resource represents, whether pre-existing data or data that is generated dynamically, depends on the implementation of the server. Often, the resource corresponds to a file or the output of an executable residing on the server.

And, the verbs it lists:

GET — Requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect. (This is also true of some other HTTP methods.) The W3C has published guidance principles on this distinction, saying, “Web application design should be informed by the above principles, but also by the relevant limitations.”

HEAD — Asks for the response identical to the one that would correspond to a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.

POST — Requests that the server accept the entity enclosed in the request as a new subordinate of the resource identified by the URI. The data POSTed might be, as examples, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.

PUT — Requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.

DELETE — Deletes the specified resource.

TRACE — Echoes back the received request so that a client can see what (if any) changes or additions have been made by intermediate servers.

OPTIONS — Returns the HTTP methods that the server supports for specified URL. This can be used to check the functionality of a web server by requesting ‘*’ instead of a specific resource.

CONNECT — Converts the request connection to a transparent TCP/IP tunnel, usually to facilitate SSL-encrypted communication (HTTPS) through an unencrypted HTTP proxy.

PATCH — Is used to apply partial modifications to a resource.

Next up

Learn why HTTP is no secret. Head over to How to Spy on Your Browser’s HTTP Requests and Responses!

Join the Discussion

    There are currently no comments.

    27 + = 35