API Servers in Node.js

Paul Querna
February 29, 2012

Background

• Web Applications:
  
  • HTML
  • CSS
  • Javascript
  • Web Sockets
  
  
• API Servers:
  
  • JSON
  • XML

In the beginning...

More Stuff!

More and More!

API Servers are hard.

API Server Features

• Authentication / Authorization
• Rate Limiting / Abuse protection
• API Versioning
• Scatter & Gather IO
• Output Generation (JSON, XML)
• Input Validation (JSON, XML)
• Fault Isolation
• Fault Isolation
• Fault Isolation
• Logging
• Usage Reporting

Today's Focus

• Output Generation (JSON, XML)
• Input Validation (JSON, XML)

Content Generation

• JSON: JSON.stringify
• XML: Who uses XML anyways?

Content Generation: Grown up.

• JSON: Munge objects to be just right, then JSON.stringify.
• XML: Who uses XML anyways? Lots of people. APIs should be easily consumable in as many languages as possible..

node-elementtree

var et = require('elementtree');

var root = et.Element('sounds');

var meow = new et.SubElement(root, 'meow',
                            {volume: '42', source: 'cats'});

var dctitle = new et.QName('http://purl.org/dc/elements/1.1/','title');

var title = new et.SubElement(root, dctitle);

title.text = "Hello World";

var doc = new et.ElementTree(root);

console.log(doc.write());
        

ElementTree generates correct XML.

<?xml version="1.0" encoding="utf-8"?>
<sounds xmlns:dc="http://purl.org/dc/elements/1.1/">
  <meow source="cats" volume="42"/>
  <dc:title>Hello World</dc:title>
</sounds>
        

Input Validation

• JSON: JSON.parse
• XML: ElementTree
• Manual Object validation, hand written error messages.

node-swiz

• Object definitions
• Field Types for serialization
• Per-field validations
• Whole object validators
• Access Controls (hidden or read only fields)

Example Swiz Definition

var def = [
  O('Node',
    {
      'fields': [
        F('key', {'val' : new Chain().isString()}),
        F('ip_address_v4', {'val' : new Chain().isIP()}),
        F('name', {'val': new Chain().isString(),
          'filterFrom': ['public']})
      ],
      'plural': 'nodes'
    })
];
        

Example Errors from Swiz

POST ....

{
    "key": "1234",
    "ip_address_v4": "x1.2.0.4"
}

{ key: 'ip_address_v4', parentKeys: [], message: 'Invalid IP' }

Example Swiz Output

{
    "key": "1234",
    "ip_address_v4": "1.2.0.4"
}

<?xml version='1.0' encoding='utf-8'?>
<node>
  <key>1234</key>
  <ip_address_v4>1.2.0.4</ip_address_v4>
</node>

Thank you!

• github.com/racker/node-swiz
• github.com/racker/node-elementtree
• docs.rackspace.com/cm/api/v1.0/cm-devguide
• paul.querna.org/slides