Skip to content

Latest commit

 

History

History
262 lines (215 loc) · 17.1 KB

README.md

File metadata and controls

262 lines (215 loc) · 17.1 KB

Liquid Prep - Backend Service

Liquid Prep backend service exposes Cloud Functions API endpoints for Liquid Prep application to query weather and crop information. The backend service is deployed and hosted on IBM Cloud. It mainly consists of 2 IBM Cloud services;

  1. IBM Cloud Functions:

    • The Cloud Functions hosts the Liquid Prep backend service which handles the requests from Liquid Prep app, process the requests to query weather data or crop data and sends back the response to Liquid Prep app.
    • The Cloud Functions exposes an API endpoint for the Liquid Prep app to send requests to get data.

  2. IBM Cloudant DB:

    • The Cloudant DB acts a storage for all the crop data which will explained in the IBM Cloudant section.

Currently the backend service is deployed and hosted on IBM Cloud Liquid Prep's account. You can also setup and deploy the Liquid Prep backend service on your own IBM Cloud account.

Instructions on how to setup, configure and deploy the backend service is as follows:

Pre-requisites

  1. IBM Cloud account:

    • Create an IBM Cloud account

    • Install IBM Cloud CLI

    • Setup the Cloud Functions CLI plug-in

    • Create IAM API key;

      • Login to IBM Cloud account.
      • Click on Manage tab on top right of the IBM Cloud dashboard. And click on Access (IAM) option to open Manage access and users dashboard.
      • Select API keys option on left pane of the dashboard.
      • Select Create an IBM Cloud API key button on right of the API keys dashboard.

      • Enter an API key name and description. Example,

      • An IAM API key will be created, copy and/or download the key and secure it safely. NOTE: This IAM API key is required later for Liquid Prep project deployment and IBM Cloud CLI login. Please copy/download and store it in a secure place. If the IAM API key is NOT copied/downloaded and stored in secure place, you will have to create new IAM API key.

    • Create Resource Group;

      • Click on Manage tab on top right of the IBM Cloud dashboard. And click on Account option to open Account dashboard.
      • Select Resource groups option on the left panel of the dashboard. Usually a Default resource group will be created when a cloud account is created. If not a new Resource group can be created by clicking on the Create button on the right of the Resource groups dashboard.

    • Create Cloud Foundry Organization;

      • From the Account dashboard, select Cloud Foundry orgs option on the left pane to open Cloud Foundry Orgs dashboard.
      • Click on Create on the top right of the dashboard to create new Organization. If an organization already exists, you can use the same.

    • Create Space;

      • From the Cloud Foundry Orgs dashboard, click on the Name of the organization to open the Space tab for the organization.
      • Click on the Add a space button the top right of the dashboard to create new Space. If a space already exists, you can use the same.

  2. Git:

  3. Liquid Prep project:

  4. The Weather Company API Key:

  5. Node and NPM:

IBM Cloud Functions

  1. Create a new IBM cloud account. If you already have an account, please log in to account.
  2. Select IBM Cloud Functions icon on left the pane of the IBM Cloud account dashboard

    Or you can search for **Functions** in search bar and select **Functions**.

  3. Select Actions option on the left pane of IBM Cloud Functions dashboard.

  4. Create new Actions by clicking the Create on top right of the dashboard, enter Action Name as liquid-prep-action. Create new Package liquidPrep. Select Node.js 12 as Runtime.

  5. Go back to IBM Cloud Functions dashboard and select APIs option on the left pane.

  6. Select Create API option on top right of the dashboard, enter API name as liquidPrep-cf-api. Let the Base path for API be default /liquidPrep-cf-api. Let other settings be default values, unless other specific entries are required. Scroll down the page and select Create.

  7. Once API is created, select the API liquidPrep-cf-api, select Manage Sharing and Keys on the left pane of the API dashboard. Enable Include API in organization-level Shared APIs view.

IBM Cloudant

  1. Enter Cloudant in the IBM Cloud search bar and select Cloudant.

  2. Under Select an environment section, enter Instance Name as Cloudant-liquidPrep.
  3. Select IAM as Authentication method.
  4. Select a suitable pricing Plan – Lite, Standard and Standard on Transaction Engine.

  5. Select Create on the bottom right pane of Cloudant dashboard. After you click Create, a message displays to say that the instance is being provisioned, which returns you to the Resource list. From the Resource list, you see the status for your instance is, Provision in progress.

  6. When status of the instance changes to Active, click the Cloudant-liquidPrep instance and select Service Credentials tab on left pane of dashboard.
  7. Select New Credential, enter Name as liquid-prep and Role as Manager. A service credential will be created.

  8. Select Manage tab on the left pane and select Launch Dashboard on the top right of the page. It will launch a Cloudant dashboard to create new database.
  9. On the Databases page, select Create Database on the top right of the Cloudant dashboard.
  10. Enter Database name as liquid-prep-crops. Select the Partitioning option as Non-partitioned. And click on Create button at the bottom.

  11. liquid-prep-crops database will be created and listed in Databases page.
  12. Select liquid-prep-crops and click on Create Document on top right of the page. A document with auto generated _id key will open.

  13. Go to Liquid Prep project directory ~/Liquid-Prep/backend/resources/crops. Open each crop document, copy the contents in the document and paste it in the New Document that was opened in liquid-prep-crops database and click Create Document button.
    Example for Corn crop;

    Corn document will be created and listed in **liquid-prep-crops** database.

  14. Similarly, repeat step 13 for all the other crops document.

Deploy Liquid Prep Backend Service

After configuring IBM Cloud Functions and Cloudant DB, the Liquid Prep backend project needs to built, bundled and deployed to IBM Cloud Functions to expose Cloud Functions API for Liquid Prep application.

  1. Go to Liquid Prep project directory ~/Liquid-Prep/backend/liquid-prep-cf and create .env file.
  2. Add following entries to the .env file;
 IAM_API_KEY=xxxxxx
 CLOUD_FUNCTIONS_URL=https://xxxxxx.appdomain.cloud/liquidprep-cf-api
 CLOUDANT_DB_URL=https://xxxxxx-bluemix.cloudant.com/
 CLOUDANT_DB_NAME=liquid-prep-crops
 WEATHER_API_KEY=xxxxxxxxxx

where the entries should be filled out as follows:

**IAM_API_KEY:** <br>
It is the API key created at the beginning when an IBM Cloud account is created. Please refer to the **Pre-requisites** section on how to create/obtain the IAM API key.

**CLOUD_FUNCTIONS_URL:** <br>
- Go to IBM Cloud dashboard.
- Click on the **Navigation Menu** on the top left corner of the dashboard.
- Select **API Management** option.
<p align="left">
    <img src="https://github.com/Call-for-Code/Liquid-Prep/blob/master/images/backend/envEntries/apiManage.PNG" width ="30%" height="30%">
</p>

- Select **Shared APIs** in **API Management** dashboard.
- The **Route** value in **Shared APIs** dashboard is the **CLOUD_FUNCTIONS_URL** value.
<p align="left">
    <img src="https://github.com/Call-for-Code/Liquid-Prep/blob/master/images/backend/envEntries/sharedApi.PNG" width ="30%" height="30%">
</p>

***CLOUDANT_DB_NAME: liquid-prep-crops*** <br>
It is the Cloudant database name which was created to add the crop documents. <br>

***CLOUDANT_DB_URL:*** <br>
The Cloudant DB URL can be obtained from its **Manage** dashboard.
- Go to IBM CLoud dashboard.
- Click on the **Navigation Menu** on the top left corner of the dashboard.
- Select **Resource List** option.
- Select **Cloudant-liquidPrep** instance under **Services** in **Resource list** dashboard.
<p align="left">
    <img src="https://github.com/Call-for-Code/Liquid-Prep/blob/master/images/backend/envEntries/cloudantService.PNG" width ="30%" height="30%">
</p>

- The **External Endpoint (preferred)** value is the **CLOUDANT_DB_URL** value.
<p align="left">
    <img src="https://github.com/Call-for-Code/Liquid-Prep/blob/master/images/backend/envEntries/cloudantEndpoint.PNG" width ="30%" height="30%">
</p>

***WEATHER_API_KEY:*** <br>
The Weather API key is obtained by subscribing to The Weather Company API services. https://www.ibm.com/products/weather-company-data-packages/details

  1. Open command terminal and execute npm install in project directories ~/Liquid-Prep/backend/liquid-prep-cf and ~/Liquid-Prep/backend/common.

  2. Log into IBM Cloud account from command terminal with ibmcloud CLI. Execute the login command,
    ibmcloud login --apikey <IAM API key> -g <Resource Group> -o <organisation> -s <space> -r <region>

    • --apikey:
      It is the API key created at the beginning when an IBM Cloud account is created. Please refer to the Pre-requisites --> IBM Cloud account --> Create IAM API key section on how to create/obtain the IAM API key.

    • -g:
      It is the Resource group of the cloud account. Usually a Default resource group will be created. If not you can create a new resource group and enter.
      Please refer to the Pre-requisites --> IBM Cloud account --> Create Resource Group section on how to create/obtain the Resource group.

    • -o:
      It is the Cloud Foundry Organization of the cloud account. Please refer to the Pre-requisites --> IBM Cloud account --> Create Cloud Foundry Organization section on how to create/obtain the Cloud Foundry Organization.

    • -s:
      It is the Space in the Cloud Foundry Organization of the cloud account. Please refer to the Pre-requisites --> IBM Cloud account --> Create Space section on how to create/obtain the Space.

    • -r:
      It is the Region of the cloud account. Region can be obtained in the selected Cloud Foundry Organization dashboard beside the Space Name.

  3. Navigate to project directory ~/Liquid-Prep/backend/liquid-prep-cf from command terminal and execute npm run deploy-dev-api.

Once the deployment is successful, go to IBM Cloud Functions dashboard, select Actions tab on the left pane and you can see liquid-prep-action instance in the Actions dashboard.

Liquid Prep APIs

The backend service is deployed in Liquid Prep cloud account and the APIs can be tested by executing them in any browser URL path.

  1. GET-WEATHER-INFO: Get weather information for a location.
    https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_weather_info?geoCode=<lat,long>&units=<metric/imperical>

    Params:

    • geoCode: Geo-coordinates (latitude, longitude) of location.
    • units: metric (e) or imperial (m)

    Example:
    Get weather information for geo-coordinates latitude 42.359, longitude 71.068 and units in metrics (e).
    https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_weather_info?geoCode=42.359,-71.068&units=e

  2. GET-CROP-INFO: Get crop information for a particular crop supported by Liquid Prep.
    https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_crop_info?id=<_id>

    Params:

    Example:
    Get crop information for Corn.
    https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_crop_info?name=1

  3. GET-CROP-INFO: Get list of all crop names supported by Liquid Prep.
    https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_crop_list