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