speakeasy-api / grpc-rest-service

Gnostic-gRPC and gRPC-Gateway Example with Generated SDKs

Example project using Gnostic to generate gRPC and gRPC-Gateway code, and the generated SDKs for Go, Python, and Node.js.

Requirements

• Docker
• VS Code
• Remote - Containers Extension

Getting Started

1. Click on the "Open in Dev Containers" badge above to open the project in a Dev Container. If this does not work, clone the repository by following your usual git workflow, then open it in VS Code.
2. Optional: Copy .env.template to .env and add your OpenAI API key.
3. Rebuid the container by running the Remote-Containers: Rebuild Container command.
4. Open a terminal in VS Code and run the following command:

go run main.go

5. Open a new terminal and run the following command:

grpcurl -plaintext -d '{"drink_name_request": {"name": "Pan Galactic Gargle Blaster"}}' localhost:50051 bar.Bar/GetDrink | sed 's/%3A/:/g; s/%2F/\//g; s/%3D/=/g; s/%3F/?/g; s/%26/\&/g' | jq

6. You should see a JSON response with the drink details.

How to Change the API

1. Edit bar.yaml.
2. Run the following command to generate the a protobuf binary:

gnostic --pb-out=. bar.yaml

3. Run the following command to generate the gRPC protobuf file with annotations:

gnostic-grpc -input bar.pb -output .

4. Run the following command to generate the gRPC and gRPC-Gateway code:

buf generate

5. Run the following command to generate the SDKs:

speakeasy generate sdk \
    --schema bar.yaml \
    --lang typescript \
    --out ./bar-sdk-typescript

6. Rebuild the container by running the Remote-Containers: Rebuild Container command.

7. Continue from step 4 in the Getting Started section.

Testing

We can test the gRPC and gRPC-Gateway services using grpcurl and curl.

Testing with gRPCurl

Run the following commands to test the gRPC service:

# Create a drink
grpcurl -plaintext -d '{"ingredients_request": {"ingredients": ["Gin", "Tonic water", "Lime juice"]}}' localhost:50051 bar.Bar/CreateDrink

# Get the drink
grpcurl -plaintext -d '{"drink_name_request": {"name": "Pan Galactic Gargle Blaster"}}' localhost:50051 bar.Bar/GetDrink

Testing with cURL

Run the following commands to test the gRPC-Gateway service:

# Create a drink
curl -X POST -H "Content-Type: application/json" -d '{"ingredients": ["Gin", "Tonic water", "Lime juice"]}' http://localhost:8080/create-drink

# Get the drink
curl -X POST -H "Content-Type: application/json" -d '{"name": "Pan Galactic Gargle Blaster"}' http://localhost:8080/get-drink

License

This project is licensed under the MIT License - see the LICENSE file for details.