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) 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) bool
  • func (c Context) Decode(v interface{}) bool
  • func (c Context) DecodeParam(param string, v interface{}) bool
  • func (c Context) Encode(v interface{})
  • 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) 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) bool

Check conditionally writes an error. If err is non-nil, Check prefixes it with msg, writes it to the response body, and returns true. Otherwise it returns false.

func (Context) Decode

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

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

func (Context) DecodeParam

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

DecodeParam decodes the specified path parameter into v, which must be a pointer value with one of the following methods:

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

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

func (Context) Encode

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

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

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.