API

Developing Locally

Coding Standards

Required Software

• Git
• NodeJS / NPM
• Homebrew
• Redis

Setup local workstation:

• Clone the Howdy-APIs repository

• npm install

• sudo npm i -g realpath

• sudo npm i -g linkemon

• Download Oracle Instant Client

• sudo mkdir -p /usr/local/oracle/instantclient_19_8/

  • Unzip and copy the Oracle Instance Client files into /usr/local/oracle/instantclient_19_8/
  • Talk to Marc, or ask another developer to filex you the Oracle Wallet files listed below. Place them in /usr/local/oracle/instantclient_19_8/network/admin/
    • tnsnames.ora
    • sqlnet.ora
    • ewallet.p12
    • cwallet.sso

• Redis

  (For more detailed instructions see https://phoenixnap.com/kb/install-redis-on-mac)

  • Install brew install redis
  • Start brew services start redis

If interested, you may also setup redis-sentinel to more closely mimic the server side behaviour. Finally, installing https://github.com/qishibo/AnotherRedisDesktopManager will provide a nice GUI for viewing your local Redis datastore.

• Set up your development environment
  • IntelliJ
    • Open the application and click File > New > Create Project from Existing Sources
    • Select the downloaded repo and follow the steps.
• Set up Environment variables - Used to store sensitive information such as passwords that should not be committed to the project.
  • Replace the bash variables in the script below with your values (Note: You may also use IntelliJ's local configuration feature.)
    • vi config/myConfig.sh

    #!/bin/bash 
          
    export BAN_ENV='${netID}' 
    export TNS_ADMIN='/usr/local/oracle/instantclient_19_8/network/admin'
    export EXTERNAL_AUTH='true'
    export ENABLE_SSL='true'
    # For TEST, TST2, DEVL and DALY
    export BAN_USER=
    export BAN_PASSWORD=
    # Either change the instance name of adjust the commented lines below to switch environments
    export BAN_CONNECTIONSTRING=TST2_HOWDYWEB
    #export BAN_CONNECTIONSTRING=TEST_HOWDYWEB
    #export BAN_CONNECTIONSTRING=DEVL_HOWDYWEB
    #export BAN_CONNECTIONSTRING=DALY_HOWDYWEB
    export REDIS_PASSWORD=${REDIS_PASSWORD_IS_PROBABLY_BLANK_FOR_LOCAL}'
    export sharedSecretKey='${SHARED_SECRET_KEY_GOES_HERE}
    export HTTP_PORT='3000'
    export FILE_LOG_LEVEL='debug'
    export CONSOLE_LOG_LEVEL='debug'
    export LOGSTASH_URL='http://localhost:9200/'
    export NPM_TOKEN='${Your_NPM_TOKEN}'
    export MY_API_APP_PATH='/Users/${netID}/TAMU_GIT/howdy_web_components/howdy_api_app/ <== adjust the path for your local environment'
    export STUDENT_USER='${PUT_TEST_ACCOUNT_NAME_HERE}'
    export STUDENT_PASSWORD='${PUT_TEST_ACCOUNT_PASSWORD_HERE}'

• Source your environment variables prior to starting the api service
  • source config/myConfig.sh

Running your Local API server

1. Open a terminal window and navigate to the repo location

• run npm link "@tamu-eis/automated-application-testing"
• run howdyApiMain.js linkemon howdyApiMain.js

Highlights of the HOWDY-APIS project

• This will be a brief description of the Project focusing on the parts that most users will need to know to create an api
  • config - This folder holds the files that will reference the local environment variables
  • controllers - This folder holds the 'controller' for the api's and in affect mostly calls an asynchronous function named get. Most people will only need to copy a file of a similar api rename it change the names inside.
  • db_apis - This is where most of the work really happens. the files here hold the implementation (pl/sql call out). again Most people will copy a file of a similar api rename it and some names inside. After doing that the sql-pl/sql will also need to be updated along with changing any binding to vars.
  • node_modules - This folder is filled with dependencies and is modified by updating the package.json file and running npm install
  • services
    • database.js - Generally not touched but handles all the connecting to the database and closing the connection after the call is done.
    • router.js - Another place that needs to be updated. generally a developer will Instantiate API endpoint (look for comment in file) and then Create a Route for API (again look for comment in file).
    • web-server.js - this only needs to be updated to update user that the web server is listening and what api's are exposed (so add your newly created api call)

Creating your own api

1. create a controller

• this will house the routed call to the appropriate db call that is written in the db_apis folder

2. create a db_apis

• this will house the db call

3. update router.js

• this update creates the programmatic route to the controller
• note: only anonymous endpoints can go before the router.use authn and authz or it will not be validated properly (Around line: 58)

4. update the table at HOWDYWEB.HWR_API_CONFIG

• this is the database that gives permission to the users that can make this api call

Production

Running PM2 & Node.js in Production Environments

Express in PROD

Express Tutorial Part 7: Deploying to production

run directly against Node.js in production

PM2

Logging

Monitoring

Encryption (TLS)

Resources

The Oracle connectivity and basic API approach was inspired by this article.

How to write production-ready Node.js Rest API — Javascript version

How to write production-ready Node.js Rest API — Typescript version

Express

Express/cors

Installing node-oracledb

Automatically send pm2 monit stats to Elasticsearch

Student Risk Dashboard API

This API will return a JSON containing students to populate the risk dashboard.

• Allowed Operations
  • GET
    • http://localhost:3000/api/atRiskStudents/$pidm
  • POST, DELETE, PUT
    • Not allowed.

sbs Account Details API

This API will return a JSON containing tuition and fees datagrid to populate the tuition and fees angular component in Howdy.

• Allowed Operations
  • GET
    • http://localhost:3000/api/sbsAccountDetails/$pidm
  • POST, DELETE, PUT
    • Not allowed.

sbs Balances API

This API will return a JSON containing sbs Balances to populate the tuition and fees angular component in Howdy.

• Allowed Operations
  • GET
    • http://localhost:3000/api/sbsBalances/$pidm
  • POST, DELETE, PUT
    • Not allowed.

student Holds API

This API will return a JSON containing studentHolds to display and set permissions for angular components in Howdy.

• Allowed Operations
  • GET
    • http://localhost:3000/api/studentHolds/$pidm
  • POST, DELETE, PUT
    • Not allowed.

curr Change My Pending Requests API

This API will return a JSON containing ??? to display ??? for angular components in Howdy.

• Allowed Operations
  • GET
    • http://localhost:3000/api/currChangeMyPendingRequests/$pidm
  • POST, DELETE, PUT
    • Not allowed.

curr Change Submit Request API

This API will return a JSON containing ??? to display ??? for angular components in Howdy.

• Allowed Operations
  • POST
    • http://localhost:3000/api/currChangeSubmitRequest/$pidm
  • GET, DELETE, PUT
    • Not allowed.

ccm Template API

This API will return a JSON containing a ccmTemplate to display angular components in Howdy.

• Allowed Operations
  • GET
    • http://localhost:3000/api/ccmTemplate/?template
  • POST, DELETE, PUT
    • Not allowed.

App

Setup instructions for the /app routing endpoints.