core

README

Core

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 core.json, see the -h help output for additional usage details.

GO

• srpc-go-types generates Go type definitions
• srpc-go-client generates Go client
• srpc-go-server generates Go server

Typescript (todo)

• srpc-ts-client generates TypeScript clients

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.

---

Documentation

Index

• Variables
• func BadRequest(message string) error
• func Error(status int, 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 WriteResponse(w http.ResponseWriter, value interface{})
• type Field
  • func BuiltinTypeFields(ff []Field) []Field
• type Method
  • func InitMethods(mm ...Method) []Method
• type ServerError
  • func (e ServerError) Error() string
• type Type
  • func InitTypes(tt ...Type) []Type
  • func (t Type) IsBuiltin() bool
  • func (t Type) IsInitialized() bool

Variables

var Bool = Type{
	Name:          "bool",
	Description:   "built-in bool",
	Fields:        nil,
	PrimaryKey:    nil,
	GoType:        "bool",
	SwiftType:     "Bool",
	SwiftDefault:  "false",
	KotlinType:    "Boolean",
	KotlinDefault: "false",
	SqlcType:      "BOOLEAN",
	// contains filtered or unexported fields
}

var Float = Type{
	Name:          "float",
	Description:   "built-in float",
	Fields:        nil,
	PrimaryKey:    nil,
	GoType:        "float64",
	SwiftType:     "Double",
	SwiftDefault:  "0.0",
	KotlinType:    "Double",
	KotlinDefault: "0.0",
	SqlcType:      "DOUBLE PRECISION",
	// contains filtered or unexported fields
}

var Int = Type{
	Name:          "int",
	Description:   "built-in integer",
	Fields:        nil,
	PrimaryKey:    nil,
	GoType:        "int",
	SwiftType:     "Int",
	SwiftDefault:  "0",
	KotlinType:    "Long",
	KotlinDefault: "0",
	SqlcType:      "BIGINT",
	// contains filtered or unexported fields
}

var String = Type{
	Name:          "string",
	Description:   "built-in string",
	Fields:        nil,
	PrimaryKey:    nil,
	GoType:        "string",
	SwiftType:     "String",
	SwiftDefault:  `""`,
	KotlinType:    "String",
	KotlinDefault: `""`,
	SqlcType:      "TEXT",
	// contains filtered or unexported fields
}

var Time = Type{
	Name:          "time",
	Description:   "built-in date",
	Fields:        nil,
	PrimaryKey:    nil,
	GoType:        "*time.Time",
	SwiftType:     "Date",
	SwiftDefault:  "Date()",
	KotlinType:    "Date",
	KotlinDefault: "Date()",
	SqlcType:      "TIMESTAMPTZ",
	// contains filtered or unexported fields
}

Functions

func BadRequest

func BadRequest(message string) error

BadRequest returns a new bad request error.

func Error

func Error(status int, message string) error

Error returns a new ServerError with HTTP status code, kind and message.

func NewRequestContext

func NewRequestContext(ctx context.Context, v *http.Request) context.Context

NewRequestContext returns a new context with ctx.

func ReadRequest

func ReadRequest(r *http.Request, value interface{}) error

ReadRequest parses application/json request bodies into value, or returns an error.

func RequestFromContext

func RequestFromContext(ctx context.Context) (*http.Request, bool)

RequestFromContext returns ctx from context.

func WriteError

func WriteError(w http.ResponseWriter, err error)

WriteError writes an error.

The message in the response uses the Error() implementation.

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 Field

type Field struct {
	Name           string `json:"name"`
	CamelName      string `json:"camel_name"`
	LowerCamelName string `json:"lower_camel_name"`
	Description    string `json:"description"`
	Type           Type   `json:"type"`
	IsArray        bool   `json:"is_array"`
}

Field model.

func BuiltinTypeFields

func BuiltinTypeFields(ff []Field) []Field

type Method

type Method struct {
	Name           string  `json:"name"` // based on filename
	CamelName      string  `json:"camel_name"`
	LowerCamelName string  `json:"lower_camel_name"`
	Description    string  `json:"description"`
	Inputs         []Field `json:"inputs"`
	Outputs        []Field `json:"outputs"`
}

Method model.

func InitMethods

func InitMethods(mm ...Method) []Method

returns Methods from dir/*.json.

type ServerError

type ServerError struct {
	Status  int
	Message string
}

ServerError is a server error.

func (ServerError) Error

func (e ServerError) Error() string

Error implementation.

type Type

type Type struct {
	Name           string   `json:"name"` // based on filename
	CamelName      string   `json:"camel_name"`
	LowerCamelName string   `json:"lower_camel_name"`
	Description    string   `json:"description"`
	Fields         []Field  `json:"fields"`
	PrimaryKey     []string `json:"primary_key"`
	GoPackage      string   `json:"go_import"`
	GoType         string   `json:"go_type"`
	SwiftType      string   `json:"swift_type"`
	SwiftDefault   string   `json:"swift_default"`
	KotlinType     string   `json:"kotlin_type"`
	KotlinDefault  string   `json:"kotlin_default"`
	SqlcType       string   `json:"sqlc_type"`
	// contains filtered or unexported fields
}

Type model.

func InitTypes

func InitTypes(tt ...Type) []Type

func (Type) IsBuiltin

func (t Type) IsBuiltin() bool

func (Type) IsInitialized

func (t Type) IsInitialized() bool