https://github.com/appointy/protoc-gen-jaal
Develop Relay compliant GraphQL server
https://github.com/appointy/protoc-gen-jaal
go golang graphql graphql-api graphql-schema graphql-server relay-server
Last synced: 3 months ago
JSON representation
Develop Relay compliant GraphQL server
- Host: GitHub
- URL: https://github.com/appointy/protoc-gen-jaal
- Owner: Appointy
- License: mit
- Created: 2019-07-03T05:12:25.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2020-01-09T04:00:56.000Z (over 6 years ago)
- Last Synced: 2025-02-01T07:31:41.745Z (over 1 year ago)
- Topics: go, golang, graphql, graphql-api, graphql-schema, graphql-server, relay-server
- Language: Go
- Size: 85 KB
- Stars: 14
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# protoc-gen-jaal - Develop Relay compliant GraphQL servers
protoc-gen-jaal is a protoc plugin used to generate [Jaal](https://github.com/appointy/jaal) APIs. The server built from these APIs is GraphQL spec compliant as well as Relay compliant. protoc-gen-jaal also handles oneOf by registering it as a Union on the schema.
## Getting Started
Let's get started with a quick example.
```protobuf
syntax = "proto3";
package customer;
option go_package = "customerpb";
import "schema/schema.proto";
service Customers {
// CreateCustomer creates new customer.
rpc CreateCustomer (CreateCustomerRequest) returns (Customer) {
option (graphql.schema) = {
mutation : "createCustomer"
};
};
// GetCustomer returns the customer by its unique user id.
rpc GetCustomer (GetCustomerRequest) returns (Customer) {
option (graphql.schema) = {
query : "customer"
};
};
}
message CreateCustomerRequest {
string email = 1;
string first_name = 2;
string last_name = 3;
}
message GetCustomerRequest {
string id = 1;
}
message Customer {
string id = 1;
string email = 2;
string first_name = 3;
string last_name = 4;
}
```
protoc-gen-jaal uses the method option *schema* to determine whether to register an rpc as query or as mutation. If an *rpc* is not tagged, then it will not be registered on the GraphQL schema. To generate Relay compliant servers, protoc-gen-jaal generates the input and payload of each mutation with clientMutationId. The graphql schema of above example is as follows:
```GraphQl Schema
input CreateCustomerInput {
clientMutationId: String
email: String
firstName: String
lastName: String
}
type CreateCustomerPayload {
clientMutationId: String!
payload: Customer
}
type Customer {
email: String!
firstName: String!
id: ID!
lastName: String!
}
type Mutation {
createCustomer(input: CreateCustomerInput): CreateCustomerPayload
}
type Query {
customer(id: ID): Customer
}
```
### Installing
The installation of protoc-gen-jaal can be done directly by running go get.
```
go get go.appointy.com/protoc-gen-jaal
```
### Usage
For a proto file customer.proto, the corresponding code is generated in customer.gq.go.
```
protoc \
-I . \
-I ${GOPATH}/src \
-I ${GOPATH}/src/go.appointy.com/protoc-gen-jaal \
--go_out=grpc=plugins:. \
--jaal_out:. \
customer.proto && goimports -w .
```
protoc-gen-jaal generates the code to register each message as input and payload. The payload is registered with the name of message. The input is registered with the name of message suffixed with "Input". protoc-gen-jaal implicitly registers field named id as GraphQL ID.
## Available Options
The behaviour of protoc-gen-jaal can be modified using the following options:
### File Option
* file_skip : This option is used to skip the generation of gq file.
### Method Option
* schema : This option is used to tag an rpc as query or mutation.
### Message Options
* skip : This option is used to skip the registration of a message on the graphql schema.
* name : This option is used to change default name of message on graphql schema.
* type : This option is used to change go type of the message in the gq file.
### Field Options
* input_skip : This option is used to skip the registration of the field on input object.
* payload_skip : This option is used to skip the registration of the field on payload object.
* id : This option is used to expose the field as GraphQL ID. Only string field can be tagged with this option.