Express.js made it easy to roll up a REST API in Node.js, and it's become the de-facto library for standing up a backend. Strongloop took that and made it even easier to create your APIs.
Strongloop created LoopBack, a tool that allows you to generate a Node.js API that's architected like Express.js, and adheres to the OpenAPI spec. You can have a production-ready web API online with Cloud Foundry and ready to go within 10 quick minutes, and it's flexible and scalable to any needs you might have as it grows.
You can learn how to do this in two short videos. Here's the first video, where you'll create the API:
And here's the second video, where you'll deploy it to Cloud Foundry on IBM Cloud:
It's important to point out that you can use any valid MongoDB service with this, but I've chosen Compose.io for this. Go to their website and sign up for a deployment. NB: compose.io charges 31 USD/mo after a free trial month. Create a database, a username and password for access, and get the connection string for it. It should look something like this:
mongodb://<user>:<password>@aws-us-east-1-portal.26.dblayer.com:17243/animalsDemo?ssl=true
Hang onto this, as you'll need this for later.
Create an account on IBM Cloud for free by going here. After that, download the IBM Cloud CLI to your local machine here and log in with the same account that you just created.
You can deploy this application anywhere that supports Cloud Foundry. Since IBM Cloud supports it out of the box, we'll use it to deploy the application.
You'll also need to make sure you have at least v6.0 of Node.js installed on your local machine. I recommend using Node Version Manager to handle your Node.js versions. In your command line, type:
touch ~/.bash_profile
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.2/install.sh | bash
source ~/.bash_profileThis makes sure you have a .bash_profile file in your root directory, installs the version manager, and restarts your terminal instance. You should be ready to install Node.js now by typing:
nvm install node
nvm use nodeThis will install the latest version of Node.js (v8.3.0 at the time of this writing) and put it into effect on your machine. If you run into problems using nvm, go here for more information. To confirm you are installed correctly, ensure that you get output for each of the following commands:
node -v
npm -vIf you're clean so far, you'll now want to install LoopBack. Type the following:
npm install -g loopback-cli
lb -vNow you're ready to create and deploy your API.
- Scaffolding your API
- Linking a Datasource
- Generating your Model Object
- Securing the API with User Authentication
- Explore Your API
Navigate to an empty folder using your command line. When you're there, type:
lbIt will start the Yeoman generator, and allow you to make selections about your API using the command line. You want to select the following options:
_-----_
| | ╭──────────────────────────╮
|--(o)--| │ Let's create a LoopBack │
`---------´ │ application! │
( _´U`_ ) ╰──────────────────────────╯
/___A___\ /
| ~ |
__'.___.'__
´ ` |° ´ Y `
? What's the name of your application? AnimalsDemo
? Which version of LoopBack would you like to use? 3.x (current)
? What kind of application do you have in mind? api-server (A LoopBack API server with local User auth)Important note: When you are choosing the name of your application, if you just hit Enter, you'll default to the folder you are currently in. If you want to specify a unique folder, type in the name of the folder you want, and LoopBack will create it for you. Keep in mind that you'll have to do all future steps from that folder.
After you enter all of your choices, npm install will run automatically and pull down all of your dependencies for you.
Next, make sure you are in your project directory at the root folder. You want to type the following into your command line:
lb datasourceJust like the previous step, Loopback will walk you through the necessary configuration steps to do. You'll enter the following:
? Enter the data-source name: ComposeMongo
? Select the connector for ComposeMongo: MongoDB (supported by StrongLoop)
Connector-specific configuration:
? Connection String url to override other settings (eg: mongodb://username:password@hostname:port/database): mongodb://animalsUsername:[email protected]
layer.com:17243/animalsDemo?ssl=true
? host:
? port:
? user:
? password:
? database:
? Install loopback-connector-mongodb@^1.4 YesIt's important to point out that, for this demo, the connection string simply overrides whatever options you would enter for the host, port, user, password, and database. You could do either one for your own datasource, but we're using a simple connection string that Compose has generated for us. Again, that string is:
mongodb://animalsUsername:[email protected]
layer.com:17243/animalsDemo?ssl=trueOnce you install the connector, you're ready to move on.
In the same directory as the previous step, you want to type the following into your command line:
lb modelJust like before, you'll be walked through the process of making a model object, all from the command line. You should get to this point:
? Enter the model name: Animal
? Select the data-source to attach Animal to: ComposeMongo (mongodb)
? Select model's base class PersistedModel
? Expose Animal via the REST API? Yes
? Custom plural form (used to build REST URL):
? Common model or server only? commonAfter we type all of this, we will then start adding properties. Here is what your three properties should look like:
Let's add some Animal properties now.
Enter an empty property name when done.
? Property name: photoURL
invoke loopback:property
? Property type: string
? Required? Yes
? Default value[leave blank for none]:
Let's add another Animal property.
Enter an empty property name when done.
? Property name: looksFriendly
invoke loopback:property
? Property type: boolean
? Required? Yes
? Default value[leave blank for none]: true
Let's add another Animal property.
Enter an empty property name when done.
? Property name: type
invoke loopback:property
? Property type: string
? Required? Yes
? Default value[leave blank for none]:After you get prompted to add a fourth property, hit Enter and it'll jump out of the model creation dialog.
At this point, you have a working API! Feel free to try it out with node ., and navigate to the API Explorer, which will be provided in the command line for you.
OR, we can skip ahead to step 4.
In the same directory as the previous step, you want to type the following into your command line:
lb aclNow, you'll be walked through the process of setting up an ACL (access control list) for your API. You want to start with the following configuration:
? Select the model to apply the ACL entry to: Animal
? Select the ACL scope: All methods and properties
? Select the access type: All (match all types)
? Select the role All users
? Select the permission to apply Explicitly deny accessThis means your API is practically inaccessible to anyone, but you can run the same command again to start selectively allowing access to it. Type lb acl again, and set up the following configuration:
? Select the model to apply the ACL entry to: Animal
? Select the ACL scope: A single method
? Enter the method name find
? Select the role Any authenticated user
? Select the permission to apply Explicitly grant accessNow your API is up to date and ready to try out.
Type node . into your command line, and enter the API Explorer URL into your web browser. It should be located, by default, at http://0.0.0.0:3000/explorer.
Once you are here, you can play around right in the API Explorer with both of your objects. Since you've set up user authentication, you'll want to navigate to the /POST method for your User object, and create a new user. After you do this, try the /GET/login method on the same class to get an access token. You can post this access token right into the API Explorer, and you can start making authenticated requests right in your browser.
It's important to point out here that you can run this anywhere Cloud Foundry is supported. Luckily, IBM Cloud supports Cloud Foundry, so for this tutorial, we'll be using that.
Log into your IBM Cloud account and navigate to your dashboard. In the upper right hand corner of the dashboard, click on the "Create App" button that looks like this:
On the left hand side of the next screen, you'll want to click on "Cloud Foundry Apps", and you'll come to a collection of runtimes you can start up. Click on the Node.js SDK button:
On the next screen, you'll be prompted to enter a name for your application. By default, your URL will be your-app-name + mybluemix.net, so make sure you choose something that will be unique. Create the application, and you'll be taken to documentation for how to use Cloud Foundry on Bluemix. I recommend reading this in your downtime!
You'll be creating and editing three files next:
.cfignoremanifest.ymlpackage.json
Create a file in your API's root directory titled .cfignore, and type this for the first and only line of the file:
node_modules/The purpose of this file is much like a .gitignore file, but for making sure you don't upload unnecessary files to your Cloud Foundry instance. CLoud Foundry will run npm install for you, as well as whatever startup commands you list in your package.json file for the Node.js runtime.
Next, you'll want to create another file in your API's root directory titled manifest.yml, and you'll want the file to look like this:
applications:
- name: david-okun-loopback-testing
memory: 256MThis file will be searched for by the IBM Cloud CLI to link your API with the right deployed instance in Cloud Foundry.
The name of the application in this file should exactly correspond to what you listed in your IBM Cloud dashboard. Also, the memory needs to be a multiple of 128, and starts at a minimum of 128M. IBM Cloud will not charge you for more than 512 megabytes of memory on your account.
Open up your package.json file from your API's root directory in your text editor, and find the following node:
"engines": {
"node": "8.1.0",
"npm": "5.1.0"
},If you can't find this node in your file, you can add it. The goal is to make sure that you specify the version of Node.js you are using locally, so that Cloud Foundry will download the correct buildpack and version of Node.js on your deployed server. This will help you make sure that you don't run into any unexpected issues on your deployment.
By now, you should have set up your IBM Cloud CLI on your machine. Before you log in for the first time, you'll need to set your API location, according to what you did with your account online by running bx api and setting it to one of the following URLs:
https://api.ng.bluemix.net(US South)https://api.eu-gb.bluemix.net(United Kingdom)https://api.au-syd.bluemix.net(Sydney)https://api.eu-de.bluemix.net(Frankfurt)
After that, you'll need to make sure you login with bx login, and you'll want to make sure you choose the same organization and space that you deployed your Cloud Foundry app when you sign in with the CLI. To check this, run bx app list, and you should see the name of your application in the output. If you don't run bx logout and bx login again to choose the right organization and development space.
If you've completed all of the above steps, run bx app push, and watch the output as Bluemix uploads your API and starts the container. Within a couple of minutes, your API should be live! You can go to the dashboard to check the status of your application.
This code pattern is licensed under the Apache Software License, Version 2. Separate third party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to the Developer Certificate of Origin, Version 1.1 (DCO) and the Apache Software License, Version 2.