Skip to content

ONLINE API

Jump to bottom
Pierre Depaz edited this page Jun 14, 2017 · 8 revisions

How to deploy your own API

Steps

Serving a webpage

(go to top)

  • Express, the framework we are using, allows us to send back some content to the user by using the response object. So far we've only look at response.send(), which allows us to just send text back, and response.json(), which allows us to send back some JSON data. If we were really crazy, we could write all of our HTML code through response.send('<html>......</html>'), but thankfully Express provides us with an easier function to send a file.

  • To send back a specific webpage, we can use response.sendFile(__dirname + "/file.html");. Whatever our file is, we are now sending it back, as long as this file is in the same directory as our server script. You can look at this example, from line 21 to 24.

  • We then notice two things. The first one is __dirname that we have to append before the file name. This tells Express in which folder to look. The second is that, if we serve additional files (such as, say, a .jpg or a .css file), these won't be served along. response.sendFile() only sends one file back. To solve that, we need to explicitly tell Express which folder to use. The convention in web development is to put all of your content inside a folder called public and include at least one file called index.html.

  • In order to tell Express that we have that folder, we need to add the following line:

app.use(express.static(__dirname + '/public'));

  • Now, Express will know that, by default, it should look in the public folder for any kind of content requested. We don't even need to say explicitly what file to send back, as long as the user knows it! For example, if there is a file called against-copyright.html and the user goes to mywebsite.com/against-copyright.html, we don't have to write some code that would explicitly tell express to send it back (something like response.sendFile(__dirname + "/public/against-copyright.html");).

  • Since our public folder is now set up, we just have to add whatever we want to that folder and that content will be automatically served!

Webhosting

(go to top)

  • Webhosting basically consists in renting out server space from some company (in which server space means 'an empty computer connected to the internet somewhere'. In our case, we will rent a server from Digital Ocean. Go to Digital Ocean. Once you've logged in, on the top right, click Create Droplet.

Create a new droplet



  • CHOOSE AN IMAGE - On the following page, select Ubuntu as a disk image. This is the Operating System which will run on your machine.

Choose an image



  • CHOOSE AN APP - Click on 'One-Click Apps', just above the disk images. On the one click apps, select "Node 4.4.5". This is the framework that will be installed on our machine (the equivalent of downloading the Node executable the way we did it on our computers).

Choose an app



  • CHOOSE A SIZE - Click on the payment plan you wish to use. The cheapest is more than enough, and will be covered for 10 months by the GitHub student developer pack.

Choose a size



  • CHOOSE A DATACENTER REGION - Click on the closest datacenter. We're choosing the datacenter that is closest to us so that our connection speed is the fastest.

Choose a datacenter region



  • Finally, click on Create and your droplet will be created! You will receive an email from DigitalOcean with your server's IP address and your credentials. The next step is to log in to our fresh server and change our password.

SSH

(go to top)

for OSX/UNIX

  • Open the Terminal, by pressing CMD+SPACE and typing "Terminal".

  • On the first line, type ssh root@XXX.XX.XX.XXX, replacing all those Xes by your server's IP address, which you should have gotten in the email from Digital Ocean.

ssh into the server

  • The first time you connect, a warning message will display. Type 'yes' and press Enter. This is your computer saying that it doesn't recognize that IP address and it might be a hack. We re-assure it that it's not a hack.

accept the new fingerprint

  • Enter the password you received in your Digital Ocean e-mail (it's normal if no characters appear in the Terminal as you type, it is a standard security measure).

  • You are now remotely connected to your server! The last thing we need to do is to change that password. Enter the current password (the one from the Digital Ocean e-mail), then your new password.

  • Make that password as elaborate as possible, using multiple words, numbers, uppercase and lowercase. These kind of servers are a prime target for hackers.

ssh into the server

  • Now that we have access to our server, we can start uploading our files!

for Windows

  • Start by downloading the PuTTY client here. PuTTY is a SSH and Telnet client which allows you to connect to remote machines using the SSH protocol.

  • Select the first on the list, putty.exe.

  • Once it is downloaded, open the .exe file (no installation needed)

  • Enter the IP address of your droplet (specified in the Digital Ocean email) in the Session tab. Click Open.

Opening PuTTY

  • A warning should appear, stating that your computer does not know the remote server's fingerprint. Click Yes. When prompted Login as: enter root. Then enter the password you have received in the Digital Ocean e-mail.

Opening PuTTY

  • Once you've successfully logged in, you will be asked to choose a new password. Make that password as elaborate as possible, using multiple words, numbers, uppercase and lowercase. These kind of servers are a prime target for hackers. Once you've chosen your new password, you're successfully logged in!

Opening PuTTY

  • The reason we have to go through PuTTY is that the Windows Command Line does not have a built-in command like ssh on OSX. However, the Windows 10 Anniversary update has made a Bash terminal available to Windows users, effectively allowing the use of ssh directly in a terminal-like window.

  • If you do not want to go through PuTTY every time you want to connect to your server, follow this guide to install the Bash Shell on Windows 10! After installing the update, you will be able to connect using the steps listed in Logging in to your server on OSX.

FTP

(go to top)

  • Start by downloading CyberDuck. CyberDuck is an FTP (File Transfer Protocol) client. It will allow us to upload and download files to our newly created droplet.

  • Once CyberDuck is downloaded, install it (Windows) and open it by double-clicking on it.

  • On the top right, click on Open Connection.

  • Then, select SFTP (SSH File Transfer Protocol) in the first dropdown menu.

  • Enter the server IP address, which you can find on your DigitalOcean homepage.

  • Enter root as Username and the new password you created when you connected to your server over SSH (using Terminal or PuTTY).

ssh into the server

  • Click Connect. You should see the progress at the bottom of the CyberDuck window. At some point, you will be ask to verify the identity of the server you're connecting to. Click OK.

ssh into the server

  • Once successfully connected, you should see... nothing (we haven't uploaded anything yet!).

  • protip: for less hassle, add your server to the bookmarks, by clicking Bookmark > New Bookmark. Enter a nickname for your server, and close the window. Next time you open CyberDuck, you can just click select that bookmark in the Quick Connect dropdown menu!*

  • Drag and drop the files you want to upload onto the CyberDuck window. Whenever you're uploading files that are already present, you will need to confirm/infirm the overwrite. In our case, we should be uploading something like a server.js file and a public folder.

  • Done! Now we need to actually run the server script we've uploaded so that we can access our website.

  • The last step is to ssh back into our remote server (either via terminal (OSX) or PuTTY (Win)). Once you are logged in, we need to re-install the node modules that we used in our offline development (e.g. Express, request, cheerio, etc.). Look at the first few lines of your server.js script and see which modules are required, then run npm install name-of-module.

  • In order to keep our script running even after we've closed our session, we need to install one more module: forever. Furthermore, we want to install it globally (that is, available to all scripts on that machine). To do so, type sudo npm install -g -you will be prompted to enter your password.

installing forever

  • Once forever is successfully installed, we can run our server script by typing forever start server.js, which is the everlasting equivalent of node server.js. Other useful commands for forever include forever stop name-of-script.js to stop a script from running (which you have to do manually, there is no such thing as CTRL+C) or forever list to see all the scripts running.

  • You can now close your SSH session, open your browser, go to the IP address of your server and you should see your website, accessible to all!

DNS

(go to top)

  • So DNS is a way to connect our IP address, what we get from our webhosting service, and an actual website name. It involves absolutely no coding but here are the few steps that you would need to follow in order to have a full-fledged website.

  • Assuming we have a server on Digital Ocean, the next step is to purchase a domain name on a Registrar. In this case, I will choose NameCheap, and will be using this service for the following steps but the concept behind it all (name servers, A Records, CNAME) are consistent across services (e.g. Google Domains).

  • First, create an account. Once you've done that, you can start searching for the domain that you want (provided that it is available).

  • Second, find the particular domain name that you like and purchase it (I recommend whois guard).

  • Once you've purchased your domain, go to your dashboard, and click on the MANAGE button next to your newly acquired domain.

  • The only thing that you need to change here are the Domain Name Servers. What we're doing is telling our Registrar (here, Namecheap) that, whenever a visitor requests our URL, we should redirect them to those specific servers, because they're the ones who actually know what is the real IP address of our machine. To that end, we will tell them to go and point to Digital Ocean's name servers.

digital ocean networking

  • That's it for our Registrar! Go back to our webhost (Digital Ocean), log in to your account and click on the Networking tab at the top.

digital ocean networking

  • Add your newly purchased domain name, and you will be prompted to add a new A Record. An A Record is basically the link between your domain name and your IP address. Type @ on the leftmost field -this is your hostname. Using @ means that any domain under your purchase (e.g. sites.mysite.com, docs.mysite.com, admin.mysite.com) will all redirect to mysite.com. On the rightmost side, pick your droplet from the dropdown menu.

digital ocean networking

  • The last minimum step is to set-up our CNAME records. CNAME (which stands for Canonical Name records basically act like aliases so that, if a visitor types in one type of URL, you can catch it and redirect it to wherever you want. The most common is to redirect www.mysite.com to mysite.com. To do that, we write www on the leftmost field and @ in the rightmost field, then click Create Record.

digital ocean networking

  • (As a final note, MX records are used to redirect mail from name@domainname.tld to wherever you want -e.g. your private email).

Using databases

(go to top)

  • Now that, in the first section of this workshop, we've dealt with saving data by directly writing JSON files, we are now going to look at a more robust database solution, called mongoose. Since mongoose is a Node implementation of MongoDB, you will need to install MongoDB.

  • The first step, as usual is to npm install mongoose, and to var mongoose = require('mongoose');

  • We are now going to open a connection to our database, which sits in a computer. In our case, our script and our database are in the same computer, and let's assume we want to call our database my_library. We would then write:

mongoose.connect('http://localhost/my_library);

var my_database = mongoose.connection;

my_database.on('open', function(){
    console.log('we have successfully connected to our database!');
    
    // this is where we will write all of our code related to Schemas (see below)
});
  • Now that we've opened a connection to our database, we need to tell it what kind of content it is going to store. These "templates" are called Schemas. Writing a Schema looks like that:
var bookSchema = new mongoose.Schema({
    title: String,
    author: String,
    synopsis: String
});
  • Mongoose now knows what to expect, so if we want to use that template to get ready to store data, we need to turn that Schema into a Model. Think of a Model as a specific instance of the more abstract Schema:
var Book;

Book = mongoose.Model('Book', bookSchema);
  • We can then create specific variables of the Book datatype.
var emma = new Book({
    title: 'Madame Bovary',
    author: 'Gustave Flaubert',
    synopsis: 'What happens when you take fiction too seriously'
});
  • If we want to save that particular instance of our Book Schema into our database, we simply need to call the save() function that is built-in the Model:
emma.save(function(error, emma){
    console.log('saved successfully!');
});
  • Mongoose has a very powerful search functionality, but the easiest is the find() function of the Model. By calling find() on a Model, we get in return an array of objects representing all of the Models in the current database.
Book.find(function(error, all_books){
    // you can do whatever you want with all_books
    // for example, loop through them
    for(var i = 0; i < all_books.length; i++){
        console.log(all_books[i]);
    };
});
  • You now know the basic functionality of creating, saving and retrieving elements of a database using mongoose/MongoDB!

Using templates

(go to top)

  • Templates are a great way to deal with the problem of having similar webpages with different content inside of it (think of user profiles on a webpage, or different threads on the same forum, etc.). In any case, these involve one template and multiple pieces of content.

  • The way this works in Node is by installing a templating engine through npm. The one we will use here is PugJS (formerly known as Jade). To install it, type npm install pug.

  • Before going directly into the code, let's start by going into our public folder (remember: this is where all of our content that is served lives). Create a views folder and, inside that folder, create a file called index.pug. index.pug should look like this:

html
    head
        title my template!
    body
        h1 my templated title!
        p my templated paragraph

  • Notice that looks very similar to HTML. That is because, what a templating engine does in part is to create, in the end, an HTML file, so the syntax needs to look similar for the sanity of the people who write them :)

  • Once we have that, in order to use it in our code, we first need to require it: var pug = require('pug');. Then we need to tell Express to use that specific templating engine, with app.set('view engine', 'pug');. Finally, we need to tell Express where are all of our templates, with app.set('views', __dirname +'/public/views');

  • Now that we've done all of this set-up work, we can then respond to any http request by writing response.render('index'); (assuming that we indeed create a file like this one inside /public/views). This will compile your .pug file into a .html file and send it back to the user.

  • Templating becomes powerful when you realize that you can also write something like this (assuming we have a custom.pug file like this one):

custom.pug

html
        head
                title Template Example

        body
                h1 templated version of "hey there"
                p specifically tailored to #{name}.
                p who is currently in a #{state} state.

server.js

var current_user = {
    'name': "pierre",
    'state': "happy"
};

response.render('custom', current_user);
  • What this does is that it looks for any variables in the template, things that are written like #{name} or #{state} and then replaces those values by the values of the data that we've passed at the same time in the response (in our case, those values are 'Pierre' and 'happy'). We could absolutely pass it a different data, which would generate a new HTML page, without actually having to re-write ALL of the HTML.

Clone this wiki locally