When you’re learning a new technology, there always a LOT of new lingo. We’ve tried to gather them all together here to help get you started:

api key

“API” stands for “Application Programming Interface”, which is a very broad term that refers (super high level) to the ways in which users or other applications can interact with an application.

Some applications (like Ensign) require permission to interact with, such as a password, token, or key.

You can get a free Ensign API key by visiting rotational.io/ensign. Your key will consist of two parts, a ClientID and a ClientSecret. The ClientID uniquely identifies you, and the ClientSecret proves that you have permission to create and access event data. You will need to pass both of these in to create an Ensign client connection.

asynchronous

An asynchronous microservice is one in which requests to a service and the subsequent responses are decoupled and can occur independently of each other.

This differs from the synchronous pattern, in which a client request (e.g. a query) is blocked from moving forward until a server response is received. Synchronous microservices can result in cascading failures and compounding latencies in applications.

Asynchronous microservices can make it a lot easier for teams to develop and deploy components independently.

Asynchronous microservices require an intermediary service usually known as a broker to hold messages emitted by a publisher that are awaiting retrieval from subscribers.

broker

An event broker is an intermediary service inside an asynchronous eventing system that stores events sent by publishers until they are received by all subscribers.

Brokers are also in charge of things like keeping events in the correct order, remembering which subscribers are listening to a topic stream, recording the last message each subscriber retrieved, etc.

In Ensign, brokers can save events permanently even after they have been retrieved (to support “time travel” — the ability to retroactively scan through an event stream to support analytics and machine learning).

client

In order to write or read data from an underlying data system (like a database or event stream), you need a client to connect to the data system and interact with it as needed (such as reading and writing data). This connection often looks something like conn = DBConnection(credentials), and after creating the conn variable, subsequent lines of code can leverage it to perform the kinds of data interactions you wish to make.

To establish a client in Ensign you need an API key. By default Ensign will read credentials from the ENSIGN_CLIENT_ID and ENSIGN_CLIENT_SECRET environment variables. If you include these in your bash profile, you can connect to Ensign with the following without having to specify your credentials in code.

package main

import (
    "fmt"

	ensign "github.com/rotationalio/go-ensign"
)

client, err := ensign.New()
if err != nil {
	panic(fmt.Errorf("could not create client: %s", err))
}

event

In an event-driven or microservice architecture, an event is the atomic element of data.

An event might look something like a dictionary, which is then wrapped in an object or struct that provides some schema information to help Ensign know how to serialize and deserialize your data.

order := make(map[string]string)
order["item"] = "large mushroom pizza"
order["customer_id"] = "984445"
order["customer_name"] = "Enson J. Otterton"
order["timestamp"] = time.Now().String()

evt := &ensign.Event{
    Mimetype: mimetype.ApplicationJSON,
    Type: &api.Type{
        Name:    "Generic",
		MajorVersion: 1,
		MinorVersion: 0,
		PatchVersion: 0,
    },
}

evt.Data, _ = json.Marshal(order)

latency

Latency can refer to both application-level communication lag (e.g. the time it takes for one part of the code to finish running before moving on to the next part) or to network communication lag (e.g. the time it takes for two remote servers on two different continents to send a single message back and forth).

Less latency is better, generally speaking.

In a microservices context, we can reduce application latency by using asynchronous communications and parallelizing functions so they run faster. Network latency can be reduced by creating more efficient communications between servers (e.g. using more scalable consensus algorithms).

microservice

A microservice is a computer application composed of a collection of lightweight services, each of which is responsible for some discrete task.

Microservices can be coordinated to communicate via events.

mime type

A MIME (Multipurpose Internet Mail Extensions) type is a label that identifies a type of data, such as CSV, HTML, JSON, or protocol buffer.

MIME types allow an application to understand how to handle incoming and outgoing data.

organization

An Ensign organization is a collection of users who are working under the same Ensign tenant.

publisher

In an event-driven microservice, a publisher is responsible for emitting events to a topic stream.

In Ensign, you can create a publisher once you have established a client. On publish, the client checks to see if it has an open publish stream created and if it doesn’t, it opens a stream to the correct Ensign node.

client.Publish(yourTopic, yourEvents...)

real-time

This is a tricky one because real-time can be used to mean different things. In some cases, “real-time” is used as a synonym for synchronous (i.e. the opposite of asynchronous). However, the term is also used to mean “very fast” or “low latency”.

sdk

SDK stands for “Software Development Kit”. Software applications designed for a technical/developer audience frequently are considerate enough to provide user-facing SDKs in a few languages (e.g. Golang, Python, JavaScript). These SDKs give users a convenient way to interact with the application using a programming language with which they are familiar.

Ensign currently offers two SDKs: the Golang SDK and a Watermill API-compatible SDK.

stream

An event stream is a flow composed of many, many individual pieces of data called events.

subscriber

In an event-driven context, a subscriber is a downstream component that is listening for events published by a publisher onto a topic.

tenant

A tenant is a user, group of users, team or company who share computing and/or storage resources.

topic

In event-driven microservices, a topic is a rough approximation of a traditional relational database table. In a relational DB, a table is a collection of related data fields arrayed as columns and rows. In an eventing context, a topic is a sequence of individual events populated with the same fields (aka schema).