This repository contains the gRPC service definitions for public EngFlow APIs.
This repository intentionally does not provide generated code for any languages to keep it free of clutter. In other words, it only provides protocol buffers definitions.
Important
TL;DR: Some APIs are still under active development and therefore are exempt from any stability guarantees and SLAs we may provide to customers. When in doubt, please reach out to us before starting to depend on an API.
This repository follows the gRPC
convention of versioning APIs independently of other
APIs and including the version of the API in the path of the package it's defined in (e.g.,
v1
of EventStore
is defined in engflow/eventstore/v1
). This allows multiple versions
of the same API to coexist and allows incremental migration to a new version of an API
while still allowing use of the old version.
However, this versioning scheme implies that APIs in this repository can be in different
stages of their lifecycle and their availability may depend on the server configuration.
Therefore, we annotate all gRPC
service
s and method
s with their availability (e.g.,
EngFlow product, server version, ...) and their stability (e.g., under development, available
to selected customers as preview, available to all customers, deprecated and scheduled for
removal, ...).
Use Bazel 5.x (or higher) to build the library. Older versions of Bazel may work as well, but are not officially supported. If you do not have Bazel installed already, we recommend installing bazelisk, which automatically fetches the latest stable version of Bazel by default.
To build all libraries run:
bazel build //...
To integrate against engflowapis
from your Bazel project, you must change your
WORKSPACE
and BUILD
files as follows.
This repository is designed to be consumed at HEAD. Please make yourself familiar with our versioning policy below before starting to depend on any APIs.
Include the API in your WORKSPACE
using http_archive
and a given commit sha
(look for the latest one at engflowapis commit history)
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "com_engflow_engflowapis",
sha256 = "a04a2d2a978355c85dff8b1018d12a8e0a1e6692add9de716fd4d1b7aa1e2a0d",
strip_prefix = "engflowapis-47aa858b498da13e7863356aaef9c6d05da0a7f2",
urls = [
"https://github.com/EngFlow/engflowapis/archive/47aa858b498da13e7863356aaef9c6d05da0a7f2.zip",
],
)
This links the engflowapis
definitions under the name com_engflow_engflowapis
.
Include the API in your BUILD
using the rules java_proto_library
and java_grpc_library
from io.grpc
. First declare the java proto library by adding as dependency
each of the required proto definitions, for instance
load("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library")
java_proto_library(
name = "engflowapis_java_proto",
visibility = ["//visibility:public"],
deps = [
"@com_engflow_engflowapis//engflow/auth:user_proto",
"@com_engflow_engflowapis//engflow/eventstore/v1:eventstore_proto",
"@com_engflow_engflowapis//engflow/eventstore/v1:notifications_proto",
"@com_engflow_engflowapis//engflow/notification/v1:notification_queue_proto",
],
)
Then add a java grpc library for each grpc service
java_grpc_library(
name = "notification_queue_java_grpc",
srcs = [
"@com_engflow_engflowapis//engflow/notification/v1:notification_queue_proto",
],
deps = [
":engflowapis_java_proto",
],
)
java_grpc_library(
name = "eventstore_java_grpc",
srcs = [
"@com_engflow_engflowapis//engflow/eventstore/v1:eventstore_proto",
],
deps = [
":engflowapis_java_proto",
],
)
Finally, include all three libraries into the dependency array of your targets.
Given that protocol buffer definitions from the engflowapis
are used,
you need to include building blocks such as protocol buffer
tools and googleapis
definitions.
Check out a full working engflow example,
that uses the
notification queue and event store APIs,
to get a better understanding on how use the API.