hive-io-rest-example

An example REST module to help describe implementation details when leveraging the Hive^io framework.

Contents

• Overview
  • Endpoints
  • Source Code
• Getting Started
  • Prerequisites
  • Installing
  • Environment Variables

Overview

This example contains a single resource to handle CRUD functionality of a generic Content object in a Restful implementation. It is a contrived but fairly robust example to illustrate different ways to use Actors in the Hive^io framework.

Endpoints

Once you get the app running using the setup instructions below, you can use the application from the following endpoint(s):

• http://localhost/contents (GET, POST)
  • POST API JSON Schema

    {
      "text": "something"
    }

• http://localhost/contents/<id> (GET, PATCH, DELETE)
  • PATCH API JSON Schema

    {
      "text": "something different"
    }

  • DELETE

NOTE: Network data models follow the Flux Standard Action specification for network transport. type and payload are derived from the routes and data sent respectively in this example.

Source Code

Getting Started

This is a straight forward CRUD example of a Content Entity that contains text, a couple Boolean flags, and a count of how many views it has. It stores these Contents in MongoDB. It leverages Hive^io's built-in telemetry solution with OpenTelemetry. Here's how to use it.

NOTE: This does not include robust error handling, authentication, and other strategies to keep the example straight forward.

Prerequisites

To use, you'll need:

• Required
  • Docker
  • Docker Compose

Installing

To start using:

1. Create the following files:
   • Dockerfile

     FROM fnalabs/hive-base-js:latest
     RUN npm install --production --no-optional hive-io-rest-example

   • docker-compose.yml

     version: '3.5'
     services:
       hive-base-js:
         build: .
         image: hive-base-js:production
         container_name: hive-base-js
         environment:
           ACTOR: ContentActor
           ACTOR_LIB: hive-io-rest-example
           ACTOR_URLS: "/contents,/contents/:id"
           CLUSTER_SIZE: 1
           HTTP_VERSION: 1
           SECURE: "false"
           TELEMETRY: "true"
           TELEMETRY_PLUGINS: '{"mongodb":{"enabled":true,"path":"@opentelemetry/plugin-mongodb"},"mongoose":{"enabled":true,"path":"@wdalmut/opentelemetry-plugin-mongoose"}}'
           TELEMETRY_SERVICE_NAME: content
           TELEMETRY_URL_METRICS: "http://collector:55681/v1/metrics"
           TELEMETRY_URL_TRACES: "http://collector:55681/v1/trace"
           MONGO_URL: "mongodb://mongo:27017/contents"
         depends_on:
           - collector
           - mongo
         ports:
           - 80:3000
         networks:
           - hive-io
       mongo:
         image: mongo:4.4.3
         container_name: mongo
         networks:
           - hive-io
         restart: on-failure
     
       # telemetry
       # TODO: you will need to define your own config for this example
       #       https://github.com/fnalabs/hive-io/blob/master/dev/collector/collector-config.yml
       collector:
         image: otel/opentelemetry-collector:0.18.0
         container_name: collector
         command: ["--config=/conf/collector-config.yml", "--log-level=ERROR"]
         depends_on:
           - zipkin
         volumes:
           - ./collector-config.yml:/conf/collector-config.yml
         networks:
           - hive-io
         restart: on-failure
       zipkin:
         image: openzipkin/zipkin:2.23.2
         container_name: zipkin
         ports:
           - 9411:9411
         networks:
           - hive-io
         restart: on-failure
     
     # networking
     networks:
       hive-io:
         driver: bridge

2. Run the following commands:

   docker-compose up

Environment Variables

The table below contains a reference to the custom environment variables used in the example. Standard environment variables are documented for the following microservice containers:

• hive-base-js

Name	Type	Default	Description
MONGO_URL	String	'mongodb://mongo:27017/contents'	url to connect to MongoDB instance