Dev: Define a NoSQL model and expose it via REST using the Loopback 3.x framework
Loopback is an open-source Node.js framework that allows you to create APIs that access back-end datasources. You can easily create models to define the structure of the data to be stored in a NoSQL database (ie. Cloudant, MongoDB, etc.) and expose them via REST APIs on a Node.js server. The Loopback CLI provides various code generators that take you through the definition process of your datasources and models. It also downloads and installs any supported connector required to create a connection to your datasource.
A datasource defines the connection to a database. It is a resource configured on the server side that describes where (and sometimes how) to access a database.
Read the Loopback 3.x Docs: https://loopback.io/doc/en/lb3/
How do I get started?
You'll need to have Node installed prior to installing the Loopback CLI tool.
> npm install -g loopback-cli
my-blog Project Tutorial
In this project, we'll create a datasource, a blogger model and a blog model that will be exposed via REST APIs using the Loopback CLI tool. The blogger model will contain a one-to-many relation with the blog model to represent that a blogger can have multiple blogs.
Create a project
To create a new Loopback project, simply use the lb
command. You can alternatively provide the name of the project, for example: lb my-blog
> lb
? What's the name of your application? my-blog
? Enter name of the directory to contain the project: my-blog
? 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)
Create a datasource
In this project, we’ll create a datasource to a Cloudant database called my-blog-db which is running on the IBM Cloud.
You can create a Cloudant database on the IBM Cloud for free with the Lite plan: https://console.bluemix.net/catalog/services/cloudant.
Don't worry if you don't have access to a database. Loopback provides an in-memory datasource by default so you can still store data somewhere, it just won't be available after the server is stopped.
If you'd rather use the in-memory datasource, skip lb datasource
. When creating your model, select db (memory)
as your datasource.
To add a new datasource, use the datasource generator lb datasource
.
~/my-blog > lb datasource
? Enter the datasource name: cloudant-ds
? Select the connector for cloudant-ds: IBM Cloudant DB (supported by StrongLoop)
? Connection String url to override other settings (eg: https://username:password@host): https://qw3rty-zxcv-4cf3-b755-eac1
8c35c949-bluemix:5fc2933h4nds0m3r0b@fd3d8–86b8-bluemix.cloudant.com
? database: my-blog-db
? username: qw3rty-zxcv-4cf3-b755-eac18c35c949-bluemix
? password: ***********************
? modelIndex:
? Install loopback-connector-cloudant@¹.0.4 Yes
(these credentials are not real ;-)
Create a model
Now we'll create our blogger and blog models. In this process, we'll configure the models to be stored on our Cloudant database and exposed via REST APIs.
To add a new model, use the model generator lb model
.
Note: The model generator will create an id
property by default. When storing a new object, this value is auto-generated.
~/my-blog > lb model
? Enter the model name: blogger
? Select the datasource to attach blogger to: cloudant-ds (cloudant)
? Select model’s base class PersistedModel
? Expose blogger via the REST API? Yes
? Custom plural form (used to build REST URL): bloggers
? Common model or server only? common
Let’s add some blogger properties now.Enter an empty property name when done.
? Property name: username
invoke loopback:property
? Property type: string
? Required? Yes
? Default value[leave blank for none]: Let’s add another blogger property.
Enter an empty property name when done.
? Property name: name
? Property type: string
? Required? No
? Default value[leave blank for none]: Anonymous
Now let's create another model:
~/my-blog > lb model
? Enter the model name: blog
? Select the datasource to attach blog to: cloudant-ds (cloudant)
? Select model’s base class PersistedModel
? Expose blog via the REST API? Yes
? Custom plural form (used to build REST URL): blogs
? Common model or server only? common
Let’s add some blog properties now.Enter an empty property name when done.
? Property name: title
invoke loopback:property
? Property type: string
? Required? No
? Default value[leave blank for none]: UntitledLet’s add another blog property.
Enter an empty property name when done.
? Property name: authorId
invoke loopback:property
? Property type: string
? Required? Yes
? Default value[leave blank for none]:Let’s add another blog property.
Enter an empty property name when done.
? Property name: text
invoke loopback:property
? Property type: string
? Required? No
? Default value[leave blank for none]:Let’s add another blog property.
Enter an empty property name when done.
? Property name: updated
invoke loopback:property
? Property type: date
? Required? Yes
? Default value[leave blank for none]:
Add any additional properties to your model
To add a new property, use the property generator lb property
.
~/my-blog > lb property
? Select the model: blogger
? Enter the property name: drafts
? Property type: array
? The type of array items: string
? Required? No
? Default value[leave blank for none]:
Create a model relation
Let's add the relationship between blogger and blog. We want to be able to access blogs from the blogger API, so we'll create the relationship from the blogger model. We'll specify the authorId field in the blog model as the foreign key.
~/my-blog > lb relation
? Select the model to create the relationship from: blogger
? Relation type: has many
? Choose a model to create a relationship with: blog
? Enter the property name for the relation: blogs
? Optionally enter a custom foreign key: authorId
? Require a through model? No
That's it! Now let's see this baby in action!
If you're curious to see what the JSON looks like, you can take a look at the .json files in my-blog/common/models/
Accessing the REST API
Start the server with node .
and open http://localhost:3000/explorer in your web browser.
~/my-blog > node .
Web server listening at: http://localhost:3000
Browse your REST API at http://localhost:3000/explorer
You should see the Loopback API Explorer with all the generated REST APIs available for the models you created. Try it out!
Pro Tip: Use Swagger Codegen to generate client SDKs for your APIs
The Loopback API Explorer is based on Swagger, which provides the swagger.json descriptor that contains the definition of all the models and the APIs. You can use the Swagger Codegen tool with the swagger.json to generate client SDKs for your Loopback APIs in various languages.
> java -jar swagger-codegen-cli-2.3.1.jar generate -i http://localhost:3000/explorer/swagger.json -l java -o my-blog-sdk
Swagger Codegen: https://github.com/swagger-api/swagger-codegen