1. Protocol Buffers
  2. Protocol Buffers AS OAS DSL

Basic

The OpenAPI Specification target for:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs. This allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

When it comes to interface descriptions for lower-level programming, we use a concept called IDL (Interface Definition Language). For example, Protocol Buffers and Apache Thrift fall into the category of IDL.

To establish a common language for OpenAPI definition, we can combine DSL and IDL, enabling concise syntax and language-agnostic interfaces for interoperability across programming languages and frameworks. This fosters collaboration and seamless API design and consumption.

ApiHug

ApiHug has made further advancements in integration and innovation, making the entire process more robust and easily adaptable for engineering purposes. It offers a comprehensive DSL design specifically catering to OpenAPI, a complete toolchain, and seamless integration with modern enterprise development, resulting in efficient and streamlined API development.

ApiHug Proto for OAS define extension to support OAS standard.

Example API Definition:

service UserAdminService {
  option (hope.swagger.svc) = {
    path: "/user/admin";
    description: "User admin server";
  };

  rpc SayHello (google.protobuf.Empty) returns (google.protobuf.Empty) {
    option (hope.swagger.operation) = {
      get: "/say-hello";
      description: "Hello from the user admin server";
      tags: "project";
      priority: MIDDLE;
      authorization:{
        low_limit_risky_mode: ANONYMOUS
      }
    };
  };


  rpc RegisterCustomer (com.apihug.demo.user.proto.api.admin.request.RegisterRequest) returns (com.apihug.demo.user.proto.api.admin.response.CustomerRegisteredResponse) {
    option (hope.swagger.operation) = {
      post: "/register";
      description: "admin try to register a new customer";
      priority: CRITICAL;
      authorization:{
        rbac:{
          authorities: ["USER_ADD"];
        }
      }
    };
  }
  
  rpc ChangePassword (com.apihug.demo.user.proto.api.admin.request.ChangePasswordRequest) returns (com.apihug.demo.user.proto.api.admin.response.CustomerPasswordUpdatedResponse) {
    option (hope.swagger.operation) = {
      post: "/change-password";
      description: "use to reset the password after password forgot";
      priority: HIGH;
      authorization:{
        rbac:{
          authorities: ["USER_ADD", "USER_DELETE"];
        }
      }
    };
  }
}

Refer

  1. gRPC-Gateway is a plugin of protoc. It reads a gRPC service definition and generates a reverse-proxy server which translates a RESTful JSON API into gRPC.
  2. Google Open API Protos public Google APIs that support both REST and gRPC protocols.
  3. The OpenAPI Specification
  4. Apihug full demo