README
¶
RPC
Simple RPC style APIs with generated clients & servers.
About
All RPC methods are invoked with the POST method, and the RPC method name is placed in the URL path. Input is passed as a JSON object in the body, following a JSON response for the output as shown here:
$ curl -d '{ "project_id": "ping_production" }' https://api.example.com/get_alerts
{
"alerts": [...]
}
All inputs are objects, all outputs are objects, this improves future-proofing as additional fields can be added without breaking existing clients. This is similar to the approach AWS takes with their APIs.
Commands
There are several commands provided for generating clients, servers, and documentation. Each of these commands accept a -schema flag defaulting to schema.json, see the -h help output for additional usage details.
Clients
rpc-dotnet-clientgenerates .NET clientsrpc-ruby-clientgenerates Ruby clientsrpc-php-clientgenerates PHP clientsrpc-elm-clientgenerates Elm clientsrpc-go-clientgenerates Go clientsrpc-go-typesgenerates Go type definitionsrpc-ts-clientgenerates TypeScript clients
Servers
rpc-go-servergenerates Go servers
Documentation
rpc-md-docsgenerates markdown documentation
Schemas
Currently the schemas are loosely a superset of JSON Schema, however, this is a work in progress. See the example schema.
FAQ
Why did you create this project?
There are many great options when it comes to building APIs, but to me the most important aspect is simplicity, for myself and for the end user. Simple JSON in, and JSON out is appropriate for 99% of my API work, there's no need for the additional performance provided by alternative encoding schemes, and rarely a need for more complex features such as bi-directional streaming provided by gRPC.Should I use this in production?
Only if you're confident that it supports everything you need, or you're comfortable with forking. I created this project for my work at Apex Software, it may not suit your needs.Why JSON schemas?
I think concise schemas using a DSL are great, until they're a limiting factor. Personally I have no problem with JSON, and it's easy to expand upon when you introduce a new feature, such as inline examples for documentation.Why doesn't it follow the JSON-RPC spec?
I would argue this spec is outdated, there is little reason to support batching at the request level, as HTTP/2 handles this for you.What does the client output look like?
See the Apex Logs Go client for an example, client code is designed to be concise and idiomatic.
Sponsored by my GitHub sponsors:
Documentation
¶
Overview ¶
Package rpc provides simple RPC style APIs with generated clients & servers.
Index ¶
- func BadRequest(message string) error
- func Error(status int, kind, message string) error
- func Invalid(message string) error
- func NewRequestContext(ctx context.Context, v *http.Request) context.Context
- func ReadRequest(r *http.Request, value interface{}) error
- func RequestFromContext(ctx context.Context) (*http.Request, bool)
- func WriteError(w http.ResponseWriter, err error)
- func WriteHealth(w http.ResponseWriter, s interface{})
- func WriteResponse(w http.ResponseWriter, value interface{})
- type HealthChecker
- type ServerError
- type StatusProvider
- type TypeProvider
- type ValidationError
- type Validator
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewRequestContext ¶
NewRequestContext returns a new context with ctx.
func ReadRequest ¶
ReadRequest parses application/json request bodies into value, or returns an error.
func RequestFromContext ¶
RequestFromContext returns ctx from context.
func WriteError ¶
func WriteError(w http.ResponseWriter, err error)
WriteError writes an error.
If err is a StatusProvider the status code provided is used, otherwise it defaults to StatusInternalServerError.
If err is a TypeProvider the type provided is used, otherwise it defaults to "internal".
The message in the response uses the Error() implementation.
func WriteHealth ¶
func WriteHealth(w http.ResponseWriter, s interface{})
WriteHealth responds with 200 OK or invokes the Health() method on the server if it implements the HealthChecker interface.
func WriteResponse ¶
func WriteResponse(w http.ResponseWriter, value interface{})
WriteResponse writes a JSON response, or 204 if the value is nil to indicate there is no content.
Types ¶
type HealthChecker ¶
type HealthChecker interface {
Health() error
}
HealthChecker is the interface used for servers providing a health check.
type ServerError ¶
type ServerError struct {
// contains filtered or unexported fields
}
ServerError is a server error which implements StatusProvider and TypeProvider.
type StatusProvider ¶
type StatusProvider interface {
StatusCode() int
}
StatusProvider is the interface used for providing an HTTP status code.
type TypeProvider ¶
type TypeProvider interface {
Type() string
}
TypeProvider is the interface used for providing an error type.
type ValidationError ¶
ValidationError is a field validation error.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
generators
|
|
|
internal
|
|
|
Package schema provides the Apex RPC schema.
|
Package schema provides the Apex RPC schema. |