hive-io-rest-example

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:

• 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
    

• 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