Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yining1023/node-express-api-boilerplate


https://github.com/yining1023/node-express-api-boilerplate

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

        
## Node.js / Express.js / MongoDb (+Mongoose) Boilerplate



This is boilerplate code for setting up a simple node.js RESTful API app using: the express.js framework, a MongoDb database (with the help of Mongoose), and hosting it on Heroku. Please refer to the following documentation for each of these components:



* Node.js: 

* Express.js: 

* Moongoose.js (for MongoDB interaction): 

* Heroku:  



### Getting started with your local development server



**Dependenices:**



1) Download node.js if you have not already . You can confirm that node is successfully installed on your machine by opening up Terminal and typing 'node'. If you don't get an error, it's installed! You can exit the node process with Ctrl+c.



2) Download and install the Heroku Toolbelt , this will give you the Heroku CLI (command line interface).



3) Set up an account at . You will be asked to enter a credit card, but the app we are doing will not incur any charges (they just need a card on file). In fact, all Heroku apps have a starter/free level.



4) Download this boilerplate repo and navigate into the code directory with Terminal. To download it, click "Download Zip" at [the repo](https://github.com/sslover/node-express-api-boilerplate)... (do not clone it).



cd path/to/this/code/directory



5) Run **npm install** to get all required libraries.



	npm install



6) We now need to setup a Git repository and Heroku app.



	git init

	git add .

	git commit -am "init commit"



7) Create the Heroku app



	heroku create



NOTE: if it is your very **FIRST** time setting up a Heroku app, you will need to upload a public key to Heroku. See . As explained in that StackOverlow link, if you don't yet have a public key, you'll be prompted to add one.



8) Now that your heroku app is set-up, you can rename it whenever you like (now or in the future):



	heroku rename your-new-name



Your app will now be available at your-app-name.herokuapp.com



You can always open your app with the command:



	heroku open



### Setting Up Your MongoDB database



Heroku has many nice add-ons that make it easier to set-up an app. For example, the MongoLabs add-on gives you a MongoDB database with a single command.



9) Add MongoLabs Starter MongoDB to your heroku app:



	heroku addons:create mongolab



If you log-in to your heroku dashboard at , you'll now see this as an add-on. Click on the 'MongoLab' link to see your database.



10) Get the Heroku MongoLab connection string into an .env file. 



	heroku config --shell | grep MONGODB_URI >> .env



Your connection string to MongoDB will now be in a **.env** file now (go have a look at the .env file). Your app connects to this database in the app.js file:



app.db = mongoose.connect(process.env.MONGOLAB_URI);



Your **.env file** is a secret config file that holds key app variables like this MongoDB URI string, and other things like 3rd Party API secrets and keys. It is specified in the .gitignore file, which means the .env file will **not** be tracked by .git and not available for others to see on github (this is good).



### Starting the Server



11) We're ready to go! Run **npm start** to start your server.



	npm start



You can stop the server with Ctrl+c.



However, a slight annoyance here is that **every** time you change your code, you'll need to stop and restart your server.



A better option is to auto restart your server after you make some changes to your code. To do this, install **Nodemon**. [Nodemon](https://github.com/remy/nodemon) will watch your files and restart the server for you whenever your code changes.



Install Nodemon (you only need to do this **once**, and then it will be installed globally on your machine). In Terminal type,



	npm install -g nodemon



Then, you can start the app with:



	nodemon



12) Open web browser to  to view the web app.



13) Stop the web server press Ctrl+c in the Terminal window.



### Push Your App to Github and Heroku



As you make changes, you'll want to periodically push your updated code base to both Github and to Heroku (where it is publicly hosted).



To get your updated code to **Heroku**, you'll need to:



	git add .

	git commit -m "your commit message"

	git push heroku master



To get your updated code to **Github**, you'll need to:



(first, create a new repo at Github; **you only need to create a repo once per project**; then, once a repo is created and you have changes to push):



	git add .

	git commit -am "your commit message"

	git push origin master



You don't need to double add and double commit though. So the following will work:



	git add .

	git commit -am "your commit message"

	git push origin master

	git push heroku master



### This App's Framework and NodeJS



This app uses the following libraries and concepts:



#### ExpressJS



ExpressJS (http://expressjs.com/) is a popular framework for building web applications in NodeJS.



#### RESTful API Routes



Web service APIs that adhere to the REST architectural constraints are called RESTful APIs (http://en.wikipedia.org/wiki/Representational_state_transfer#Applied_to_web_services). HTTP based RESTful APIs are defined with these aspects:



* base URI, such as http://example.com/resources/ or http://example.com/api/

* an Internet media type for the data. We are using JSON, but it can be any other valid Internet media type (e.g. XML, Atom, microformats, images, etc.)

* standard HTTP methods (e.g., GET, PUT, POST, or DELETE) and standardized and descriptive naming in API endpoints



Typical REST queries will look like:



* CREATE - http://example.com/api/create (POST)

* RETRIEVE 1 - http://example.com/api/get/:id (GET)

* RETRIEVE ALL - http://example.com/api/get (GET)

* UPDATE - http://example.com/api/update/:id (PUT)

* DELETE - http://example.com/api/delete/:id (DELETE)



The above are typically called API endpoints, and client applications interact with your API by sending requests to these endpoints. Remember, a client can be anything that can send an HTTP request, such as a browser, a mobile app, an Arduino Yun, etc.



Routing is how your app handles these incoming HTTP requests: performing the appropriate action and responding back to the client.



In node.js (using Express), this is done through executing a callback function. In human language: 



	when this request is received, perform this action, and respond back (usually with JSON).



For example:



  // when the user requests the 'api/get' route, call a function that retrieves the data, and responds back



	router.get('/api/get', function(req, res, next){

		// step 1 - code to retrieve data

		// step 2 - code to respond back with res.json();

	})



-----



#### App Dependencies and package.json



A nice part about the ExpressJS framework (and nodejs in general) is the NPM system. NPM stands for Node Package Manager, and it allows us to include helpful node packages (libraries) that we can use in our app.



For example, open up package.json. You can see we are setting our dependent packages. When you run npm install, all of these dependencies will be installed in your node_modules folder.



package.json

	

	"dependencies": {

	  "body-parser": "~1.13.2",

	  "cookie-parser": "~1.3.5",

	  "debug": "~2.2.0",

	  "express": "~4.13.1",

	  "mongoose": "^4.1.10",

	  "morgan": "~1.6.1",

	  "node-env-file": "^0.1.7",

	  "serve-favicon": "~2.3.0"

	}



Dependencies are then declared in the app.js like:



	var express = require('express');

	var path = require('path');

	var favicon = require('serve-favicon');

	var logger = require('morgan');

	var cookieParser = require('cookie-parser');

	var bodyParser = require('body-parser');

	var mongoose = require('mongoose');

	var env = require('node-env-file');



To add a new node package, do the following in terminal:



	npm install --save nameOfPackage



The --save flag will automatically include the package in package.json as a dependency.