gRPC API

Developer Guide

This guide explains the new SpaceONE API specification which extends the spaceone-api.

git clone https://github.com/cloudforet-io/api.git

Create new API spec file

Create new API spec file for new micro service. The file location must be

proto/spaceone/api/<new service name>/<version>/<API spec file>

For example, the APIs for inventory service is defined at

proto
└── spaceone
    └── api
        ├── core
        │   └── v1
        │       ├── handler.proto
        │       ├── plugin.proto
        │       ├── query.proto
        │       └── server_info.proto
        ├── inventory
        │   ├── plugin
        │   │   └── collector.proto
        │   └── v1
        │       ├── cloud_service.proto
        │       ├── cloud_service_type.proto
        │       ├── collector.proto
        │       ├── job.proto
        │       ├── job_task.proto
        │       ├── region.proto
        │       ├── server.proto
        │       └── task_item.proto
        └── sample
            └── v1
                └── helloworld.proto

If you create new micro service called sample, create a directory proto/spaceone/api/sample/v1

Define API

After creating API spec file, update gRPC protobuf.

The content consists with two sections. + service + messages

service defines the RPC method and message defines the request and response data structure.

syntax = "proto3";

package spaceone.api.sample.v1;

// desc: The greeting service definition.
service HelloWorld {
  // desc: Sends a greeting
  rpc say_hello (HelloRequest) returns (HelloReply) {}
}

// desc: The request message containing the user's name.
message HelloRequest {
  // is_required: true
  string name = 1;
}

// desc: The response message containing the greetings
message HelloReply {
  string message = 1;
}

Build API spec to specific language.

Protobuf can not be used directly, it must be translated to target langauge like python or Go.

If you create new micro service directory, udpate Makefile Append directory name at TARGET

TARGET = core identity repository plugin secret inventory monitoring statistics config report sample

Currently API supports python output.

make python

The generated python output is located at dist/python directory.

dist
└── python
    ├── setup.py
    └── spaceone
        ├── __init__.py
        └── api
            ├── __init__.py
            ├── core
            │   ├── __init__.py
            │   └── v1
            │       ├── __init__.py
            │       ├── handler_pb2.py
            │       ├── handler_pb2_grpc.py
            │       ├── plugin_pb2.py
            │       ├── plugin_pb2_grpc.py
            │       ├── query_pb2.py
            │       ├── query_pb2_grpc.py
            │       ├── server_info_pb2.py
            │       └── server_info_pb2_grpc.py
            ├── inventory
            │   ├── __init__.py
            │   ├── plugin
            │   │   ├── __init__.py
            │   │   ├── collector_pb2.py
            │   │   └── collector_pb2_grpc.py
            │   └── v1
            │       ├── __init__.py
            │       ├── cloud_service_pb2.py
            │       ├── cloud_service_pb2_grpc.py
            │       ├── cloud_service_type_pb2.py
            │       ├── cloud_service_type_pb2_grpc.py
            │       ├── collector_pb2.py
            │       ├── collector_pb2_grpc.py
            │       ├── job_pb2.py
            │       ├── job_pb2_grpc.py
            │       ├── job_task_pb2.py
            │       ├── job_task_pb2_grpc.py
            │       ├── region_pb2.py
            │       ├── region_pb2_grpc.py
            │       ├── server_pb2.py
            │       ├── server_pb2_grpc.py
            │       ├── task_item_pb2.py
            │       └── task_item_pb2_grpc.py
            └── sample
                ├── __init__.py
                └── v1
                    ├── __init__.py
                    ├── helloworld_pb2.py
                    └── helloworld_pb2_grpc.py

References

[Google protobuf] https://developers.google.com/protocol-buffers/docs/proto3