Poe Guide

Initializing

Let's navigate to a new directory like we did earlier.

mkdir -p ~/Projects/mndvns/todo-api
cd ~/Projects/mndvns/todo-api
poe create api

Once again, we're asked to fill some project fields. Let's use the following values:

project: todo-api
description: todo api
port: 5001

And the confirmation should resemble

{
  "project": "todo-api",
  "username": "mndvns",
  "email": "mail@mndvns.com",
  "fullname": "Michael Andrew Vanasse",
  "description": "todo api",
  "PORT": "5001"
}

Just like before, let's run

make start

Once it's running, we'll check out localhost:5001 and see

Nice! So if everything's working right, we should be able to see this API mounted on our UI under /api. Let's check...

Bam. Done and done.

Login

Let's have the api to serve a login form and a signup form on /. Change api.js from

api.get('/', function(req, res, next) {
  res.json({
    app: {
      name: 'todo-api',
      description: 'todo api',
      author: {href: req.base + '/author'}
    }
  });
});

to

api.get('/', function(req, res) {
  res.json({
    signup: {
      method: 'POST',
      action: req.base,
      input: {
        _action: {
          type: 'hidden',
          value: 'signup'
        },
        username: {
          type: 'text',
          required: true
        },
        password: {
          type: 'password',
          required: true
        },
        'first-name': {
          type: 'text',
          placeholder: 'first name'
        },
        'last-name': {
          type: 'text',
          placeholder: 'last name'
        }
      }
    },
    login: {
      method: 'POST',
      action: req.base,
      input: {
        _action: {
          type: 'hidden',
          value: 'login'
        },
        username: {
          type: 'text',
          required: true
        },
        password: {
          type: 'password',
          required: true
        }
      }
    }
  });
});

Take a look: we're giving back two forms: login and signup, each of which submit a POST to our root, /. But if we submit the forms now, we wouldn't get any response; we need to add endpoints in our API for POST /.

Let's add the following lines to our api.js:

api.post('/', function(req, res, next) {
  var b = req.body;
  if (b._action === 'login') return next('route');
  if (!b.username || !b.password) return res.send(400);

  // TODO
  // save user then
  // redirect to user page

});

api.post('/', function(req, res, next) {
  var b = req.body;
  var username = b.username;
  if (!username) return res.send(400);

  // TODO
  // find user then
  // verify credentials
  // redirect to user page

});

Obviously, this still won't work. We need some way of storing our users. Let's use mongoose.js.

Mongoose

In our app's root, run

npm i --save mongoose

And make sure you have mongodb installed, then go to a fresh terminal and run

mongod

brew install mongodb

Now, at the top of api.js right under var api = ... around line 14, add

var mongoose = require('mongoose');
mongoose.connect('mongodb://localhost/todo-api');

var Schema = mongoose.Schema;
var ObjectID = Schema.ObjectId;

var UserS = new Schema({
  username: String,
  password: String,
  firstName: String,
  lastName: String
});

var User = mongoose.model('User', UserS);

api.param('user', function(req, res, next, id) {
  req.userBase = req.base + '/' + id;
  User.findById(id, function(err, user) {
    if (err) return next(err);
    if (!user) return res.send(404);
    res.locals.user = user;
    next();
  });
});

And back at our POST / endpoints, we can add the user handling like so:

api.post('/', function(req, res, next) {
  var b = req.body;
  if (b._action === 'login') return next('route');
  if (!b.username || !b.password) return res.send(400);
  var user = new User(bodyToUser(b));
  user.save(function(err) {
    if (err) return next(err);
    res.redirect(req.base + '/' + user._id);
  });
});

api.post('/', function(req, res, next) {
  var b = req.body;
  var username = b.username;
  if (!username) return res.send(400);
  User.find({username: username}, function(err, users) {
    if (err) return next(err);
    if (!users || !users[0]) return res.send(404);
    var user = users[0];
    if (user.password !== b.password) return res.send(401);
    res.redirect(req.base + '/' + user._id);
  });
});

So let's try it out! If you got the hyper.chrome extension, you can actually fill and submit forms right in the browser. Let's try it.

Go to localhost:5000/api and fill out the signup form for

username: rambo
password: 123
first name: John
last name: Rambo

Now let's use mongo's command-line tool to query the database and see if we succeeded. In a new terminal, run

mongo

This is mongo's interactive shell. If we check our database for users...

> use todo-api
switched to db todo-api
> db.users.find({}).toArray()
[
        {
                "_id" : ObjectId("54c703a9ea6c44c06a625044"),
                "username" : "rambo",
                "firstName" : "John",
                "lastName" : "Rambo",
                "password" : "123",
                "__v" : 0
        }
]
>

Booya! We have out first user, John Rambo.

Wiring It Up

Now let's return to our UI app, which is still running on localhost:5000.

Let's make that loging page we made earlier into the new home page. Instead of rerouting users, we'll just default to having them login or signup. That's a pretty good practice, right?

Remember where we added our /login route? We're just going to change it right there.

In case you forgot, we're going to navigate to the public/javascript/routes.js file. We'll change it from

module.exports = {
  '/': 'index',
  '/login': 'login'
};

to

module.exports = {
  '/': 'login'
};

Again, the key / signifies the route, and the value login signifies the partial that will be loaded on the page.

So now if we navigate to our root at localhost:5000...

That's odd, it doesn't seem to have changed... even though we've saved the files, the server isn't picking it up.

1. Build Error

2. Cached Resources

Since we'll be working very closely with APIs, it's important to remember that your browser has some development gotchas that you'll stumble upon now and then. Usually, it's related to caching in one form or another.

Remember to disable your cache (unless specifically testing it). In Chrome, you can do this easily by opening the Developer Tools and clicking Disable Cache in the Network tab.

3. Server Resart Required

There we are. Now, instead of hard coding the values, let's use the forms that the API's providing.

If you're not familiar with hyper+json, you should give the spec a quick once over. We'll be referencing it often, on the front- and back-end of our applications.

To render hyper+json forms, we'll use the ng-hyper angular/hypermedia client.

Again, if you're not familiar with ng-hyper at all, here are the docs so you can refer to terms or concepts as we go.

Here's our ng-hyper-ized login form in login.jade:

form(data-hyper-form=".login")
  div(data-ng-repeat="input in inputs")
    input(data-hyper-input="input")
  input.button-primary(type="submit" value="Login")

It doesn't look much different than our old form. But now we've relieved the front-end of deciding how to connect to the server; the ng-hyper client has mounted the action and method for us, so this form is ready to go.

Hmm, it doesn't seem to work... or does it? Well, we told it not to. User foo doesn't exist, which means a 404 is exactly the right response. We handle this at about line 100 of our api.js. Here's a refresher if you're lazy...

api.post('/', function(req, res, next) {
  var b = req.body;
  var username = b.username;
  if (!username) return res.send(400);
  User.find({username: username}, function(err, users) {
    if (err) return next(err);
    if (!users || !users[0]) return res.send(404);
    var user = users[0];
    if (user.password !== b.password) return res.send(401);
    res.redirect(req.base + '/' + user._id);
  });
});

Ah, that's right; our user's name is rambo. Let's try that.

Another 404, but this one is different: it tried to redirect us to another page, just like we told it to in our api.js:

res.redirect(req.base + '/' + user._id);

So now let's head back to the front end to make out user's page.