jape

README

jape

jape is a "micro-framework" for building JSON-based HTTP APIs. It includes:

• A generic client type that speaks JSON
• A Context type for handlers, with convenient methods for JSON and error handling
• A static analyzer that ensures parity between client and server definitions

Usage

import (
    "net/http"
    "go.sia.tech/jape"
)

func helloHandler(jc jape.Context) {
    var greeting string
    if jc.Decode(&greeting) {
        jc.Encode(greeting + ", " + jc.PathParam("name"))
    }
}

func NewServer() http.Handler {
    return jape.Mux(map[string]jape.Handler{
        "POST /hello/:name": helloHandler,
    })
}

type Client struct {
    c jape.Client
}

func (c Client) Hello(name, greeting string) (resp int, err error) {
    err = c.c.POST("/hello/"+name, greeting, &resp)
    return
}

Did you notice the error in the example code? If we run japecheck, it reports:

example.go:24:43 Client has wrong response type for POST /hello/:name (got int, should be string)

Note that japecheck is defined in a separate module to avoid dragging in unnecessary dependencies. To install it, run go install go.sia.tech/jape/japecheck.

Documentation

Index

• func AuthMiddleware(handler http.Handler, requiredPass string) http.Handler
• func Mux(routes map[string]Handler) *httprouter.Router
• type Client
  • func (c *Client) Custom(method, route string, d, r interface{})
  • func (c *Client) DELETE(route string) error
  • func (c *Client) GET(route string, r interface{}) error
  • func (c *Client) POST(route string, d, r interface{}) error
  • func (c *Client) PUT(route string, d interface{}) error
• type Context
  • func (c Context) Check(msg string, err error) error
  • func (c Context) Custom(req, resp interface{})
  • func (c Context) Decode(v interface{}) error
  • func (c Context) DecodeForm(key string, v interface{}) error
  • func (c Context) DecodeParam(param string, v interface{}) error
  • func (c Context) Encode(v interface{})
  • func (c Context) Error(err error, status int) error
  • func (c Context) PathParam(param string) string
• type Handler

Functions

func AuthMiddleware

func AuthMiddleware(handler http.Handler, requiredPass string) http.Handler

AuthMiddleware enforces HTTP Basic Authentication on the provided handler.

func Mux

func Mux(routes map[string]Handler) *httprouter.Router

Mux returns an http.Handler for the provided set of routes. The map keys must contain both the method and path of the route, separated by whitespace, e.g. "GET /foo/:bar".

Types

type Client

type Client struct {
	BaseURL  string
	Password string
}

A Client provides methods for interacting with an API server.

func (*Client) Custom

func (c *Client) Custom(method, route string, d, r interface{})

Custom is a no-op that simply declares the request and response types used by a client method. This allows japecheck to be used on endpoints that do not speak JSON.

func (*Client) DELETE

func (c *Client) DELETE(route string) error

DELETE performs a DELETE request.

func (*Client) GET

func (c *Client) GET(route string, r interface{}) error

GET performs a GET request, decoding the response into r.

func (*Client) POST

func (c *Client) POST(route string, d, r interface{}) error

POST performs a POST request. If d is non-nil, it is encoded as the request body. If r is non-nil, the response is decoded into it.

func (*Client) PUT

func (c *Client) PUT(route string, d interface{}) error

PUT performs a PUT request, encoding d as the request body.

type Context

type Context struct {
	ResponseWriter http.ResponseWriter
	Request        *http.Request
	PathParams     httprouter.Params
}

A Context contains the values relevant to an HTTP handler.

func (Context) Check

func (c Context) Check(msg string, err error) error

Check conditionally writes an error. If err is non-nil, Check prefixes it with msg, writes it to the response body (with status code 500), and returns it. Otherwise it returns nil.

func (Context) Custom

func (c Context) Custom(req, resp interface{})

Custom is a no-op that simply declares the request and response types used by a handler. This allows japecheck to be used on endpoints that do not speak JSON.

func (Context) Decode

func (c Context) Decode(v interface{}) error

Decode decodes the JSON of the request body into v. If decoding fails, Decode writes an error to the response body and returns it.

func (Context) DecodeForm

func (c Context) DecodeForm(key string, v interface{}) error

DecodeForm decodes the form value with the specified key into v, which must implement one of the following methods:

UnmarshalText([]byte) error
LoadString(string) error

The following basic types are also supported:

*int
*bool

If decoding fails, DecodeForm writes an error to the response body and returns it. If the form value is empty, no error is returned and v is unchanged.

func (Context) DecodeParam

func (c Context) DecodeParam(param string, v interface{}) error

DecodeParam decodes the specified path parameter into v, which must implement one of the following methods:

UnmarshalText([]byte) error
LoadString(string) error

If decoding fails, DecodeParam writes an error to the response body and returns it.

func (Context) Encode

func (c Context) Encode(v interface{})

Encode writes the JSON encoding of v to the response body.

func (Context) Error

func (c Context) Error(err error, status int) error

Error writes err to the response body and returns it.

func (Context) PathParam

func (c Context) PathParam(param string) string

PathParam returns the value of a path parameter. If the parameter is undefined, it returns the empty string.

type Handler

type Handler func(Context)

A Handler handles HTTP requests.