API Definition

This document explains how to define and use APIs (application programming interfaces) at Buzzvil. Interfaces are defined using Protocol Buffers.

Guidelines

API-First Approach

Use an API-first approach when building services. Define the API before developing the server or client service. This lets teams work in parallel, speeds up development, and makes APIs more stable. For details, see Understanding the API-First Approach to Building Products.

Defining an API

API Repository

Define APIs in the buzzapis repository, which contains all API definitions for Buzzvil’s internal services. For project setup and usage, see the repository’s README.

How to Define an API

Use Protocol Buffers to define APIs. See the Protocol Buffers documentation for syntax details.

Note. Buzzvil uses proto3 syntax.

API Naming Conventions

Refer to the Google Cloud API naming conventions when naming APIs.

Points to Remember

• Package names end with the version, e.g. package buzzvil.library.v1;.
• Method names follow the VerbNoun format.

Example API Definition

syntax = "proto3";
package buzzvil.library.v1;

service Library {
  rpc GetBook(GetBookRequest) returns (Book) {}
}

message GetBookRequest {
  string id = 1;
}

message Book {
  string title = 1;
  string author = 2;
}

Supporting HTTP/JSON APIs

Protocol Buffers can support HTTP/JSON APIs as well as gRPC. Using Googleapis, gateways such as gRPC Gateway or Envoy can translate HTTP requests into gRPC requests. For details, see Transcoding HTTP/JSON to gRPC.

Defining an HTTP API

Use google/api/annotations.proto to define an HTTP API. Add an option to the rpc definition as shown below. For syntax and usage, see Transcoding HTTP/JSON to gRPC and google/api/http.proto.

syntax = "proto3";
import "google/api/annotations.proto";
package buzzvil.library.v1;

service Library {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
            get: "/v1/books/{id}"
    };
  }
}

Publishing APIs

API definitions are built into language-specific libraries using tools such as Protocol Buffers and Swagger. The resulting libraries are published through each language’s package management system.

Package Information

Each API’s package information is managed in a package.json file in its directory. The name and version fields are required; other information may also be included. Do not edit version manually after the initial creation. It is set automatically from pull request information when the change is merged into master.

Example package.json

{
    "name": "book",
    "version": "0.1.0",
    "description": "Book service provides library data."
}

Package Management Systems

Go

Go API libraries use github.com as their package management system. The generated Go API files are added to the buzzapis repository at build time. For usage, see Go Projects.

Python

Python API libraries are managed through Buzzvil’s internal PyPI service. For usage, see Python Projects.

Java

Java API libraries are managed through Bintray. Separate gRPC and HTTP libraries are built and published. For usage, see Java Projects.