Developing Custom VersionOne Apps 101 Series Guide

In the introduction to this series we talked about why we're doing this series: to collaborate better with you, our users, and to help you experience Enjoyment, Understanding, and Achievement with our APIs and platform. As such, this series is highly experimental, and nothing about the approach herein is "set in stone". It comes out of some recent work we've done to enable a few customers to use JSON more easily. It's a progressive series, comprised of how to articles and a few asides that delve into the fundamental architecture of the web, HTTP, REST, and the more recent Linked Data project. In addition to the technologies and techniques mentioned in the introduction, you'll also learn about the motivations of key people who built and pioneered the web's evolution, like Tim Berners/Lee, Roy Fielding, and Brendan Eich. I hope you enjoy it, and please share any feedback for improving the series as you read. / Josh Gough

Series Articles

The series is broken into sections. The comments below indicate the theme for each and the experience levels that apply to them to help you decide where to start.

Section 1: Introduction

Experience Levels: All levels

Read these first, regardless of your web development experience level to get a good background and see a sample app.

• Enjoyment, Understanding, Achievement: Introducing the Developing Custom VersionOne Apps 101 Series
• This document: Developing Custom VersionOne Apps 101 Series Guide
• VersionOne Feature Requestor Sample Custom App: Introduction and Why You'd Need It
• Test Drive the VersionOne Feature Requestor Sample Custom App

Section 2: Web and HTTP Fundamentals: Simple Ideas for Linking the Whole, Wide World

Experience Levels: Beginner to Novice

If you don't yet have experience using HTML and JavaScript, but you'd like to complete this series either to learn more about programming against the VersionOne API, start with these articles which explain the basics of why the web exists, and how it is powered by the Hypertext Transfer Protocol standard (HTTP):

• Hello HTTP: How to GET What You Want and POST What Ya Got on the Web
• How to Spy on Your Browser's HTTP Requests and Responses!
• The Evolution of the Web is Being YouTubivised, and it's Linked
• PUT yourself in a State of REST // How to GET the Web's Architecture

Section 3: Understand REST APIs and How To Consume the VersionOne REST Data API with jQuery.ajax

Experience Levels: Novice to Intermediate

If you have some experience making web pages with HTML and JavaScript, but are new to the concept of using Application Programming Interfaces  (APIs), or are new to Representation State Transfer (REST) and REST/based APIs, then you can probably start here:

• Peer Under the Hood of the VersionOne Feature Requestor Sample Custom App (Still a work in progress on GitHub)
• Understand How and Why REST APIs Work // Demonstrated with the VersionOne Data API
• How To Query the VersionOne REST Data API for User Stories in JSFiddle with jQuery, JSON, HTTP GET, and 9 Lines of Code
• How To Update a User Story with the VersionOne REST Data API in JSFiddle with jQuery, JSON, HTTP POST, and 20 Lines of Code
• How To Use jQuery to GET a User Story in JSON Format from the VersionOne REST Data API and Render it as HTML

Section 4: Build a Story Editor with JSFiddle, HTML, jQuery, JSON, Backbone.js, and Backbone Forms for Extra Magic

Experience Level: Intermediate

If you're an experienced web developer already comfortable with jQuery or other JavaScript libraries, you can jump in here:

• How To Build a Barebones User Story Editor in JSFiddle with jQuery, JSON, and the VersionOne REST Data API
• Understand jQuery's Magic in the Barebones User Story Editor
• How To Build a Backbone/Fortified User Story Editor for the VersionOne REST Data API
• Understand Backbone Forms and Backbone.Model's Two/Way Data Binding by Playing Around in the Chrome Developer Console

Section 5: Use VersionOne Metadata to Dynamically Build the Story Editor, Plus Some Caffeine!

Experience Levels: Intermediate to Advanced

Have you already pre/ordered jQuery creator John Resig's book Secrets of the JavaScript Ninja? Then, please open a new tab and head for VersionOne Careers! Seriously, you might want to jump into the last couple of articles to see how to use all three VersionOne REST APIs: Data, Meta, and Localization. You'll see how to inherit and override parts of Backbone.Model and Backbone.sync to consume the VersionOne API, and will use some other handy functions of Underscore.js in these articles:

• The VersionOne MetaMorformizr App // Using the VersionOne REST Meta and Localization APIs to GET Serious
• Just for Fun: Convert MetaMorformizr to CoffeeScript
• The Unsorted History, and Bright, Cloudy Future of JavaScript (Work in progress)

Note: Do you find this still too basic? Are you already criticizing my example choice of Backbone.js? Good. Then, maybe you can help our community refactor either the MetaMorformizr App or the original VersionOne Feature Requestor Sample Custom App to be something you would feel proud of saying you helped build for the open source community. We'd love the help.

Additional Resources

For more web background, as well as a look into more modern features of HTML 5, try these resources:

• P2PU Webmaking 101 Free Course // P2PU is a great way to learn with peers online. This multipart course will get you started in HTML, CSS, and JavaScript
• WebPlatform.org Beginners Guide // open community with hands/on tutorials and standards documentation, backed by the web's biggest players
• HTML 5 Rocks // great site with more advanced and powerful demonstrations of HTML 5 features. Try HTML5 Web Development To The Next Level, or more HTML5 Demos

For more REST, and more properly Hypermedia, API information, try these:

• Ryan Tomayko's very brief REST introduction // what REST is all about. It can help you understand the concepts without needing to dive into code
• Building Web Services the REST Way // brief, but classic introduction to REST/based web services by Roger L. Costello
• Why REST APIs must be hypertext/driven // HTTP, Apache, and REST pioneer Roy Fielding's HATEOAS blog post
• Designing and Implementing Hypermedia APIs // article by Mike Amundsen, author, and organizer of the REST Fest conference and video archive
• Programmable Web // directory full of thousands of Web APIs available today

Finally, if you are intrigued by the increasingly popular "real/time web", you should check out the following very cool and exciting libraries. Note, however, these are all still in the early stages of development, relatively speaking, and it's still an open question as to the best way to use these technologies in conjunction with REST. What do you think?All of these are based on the concept of publish/subscribe messaging from the web server to the client/browser. Here they are:

• HTML 5 WebSockets
• Socket.io
• Faye (and the Bayeux protocol from the Dojo Foundation)
• Meteor
• Derby.js
• SignalR
• Firebase