kurz/api/api.go

/*
The Kurz Web API exposes HTTP routes for JSON clients, route names to access them, and types for the requests and responses.

  - GET "/<short>" : resolve a short URL
    - Handler: handleGetShort()
    - Success: 307 to matching target URL
    - Client request incorrect: 400
    - Short not yet defined: 404 no matching target
    - Target blocked for permission reasons: 403
    - Target legally censored: 451
    - Server failure: 50*
  - POST "/" with <target>: create a short URL from a target URL
    - Handler: handlePostTarget()
    - Success: 201 with <new short>
    - Already existing short: 409 with <existing short>
    - Target blocked for permission reasons: 403
    - Target legally censored: 451
    - Server failure: 50*

Code 451 MAY be replaced by 403, for example when legal censorship includes a
gag order, super-injunction (UK), National security letter (US) or similar
mechanisms.

These routes are exposed by running SetupRoutes(address), which is enough to
configure the Kurz domain API. Be sure to also configure the domain SPI to have
a complete application.
*/
package api

import (
	"github.com/gorilla/mux"
)

// Short is the type of responses provided by the Web API from a target.
type Short struct {
	Short string `json:"short"`
}

// Target is the type of requests accepted by the Web API for target submissions.
type Target struct {
	Target string `json:"target"`
}

// Route names.
const (
	RouteGetShort   = "kurz.api.get_short"
	RoutePostTarget = "kurz.api.post_target"
)

// Content types.
const (
	// JsonType is the MIME JSON type.
	JsonType = "application/json"

	JsonTypeHeader = JsonType + "; charset=utf-8"

	// JsonTypeRegex is a regex matching the MIME JSON type anywhere
	JsonTypeRegex = JsonType
)

// SetupRoutes() configures Web API routes on the passed mux.Router.
func SetupRoutes(router *mux.Router) {
	// BUG(fgm): improve Accept header matchers once https://github.com/golang/go/issues/19307 is completed.
	router.HandleFunc("/{short}", handleGetShort).
		HeadersRegexp("Accept", JsonTypeRegex).
		Methods("GET", "HEAD").
		Name(RouteGetShort)
	router.HandleFunc("/", handlePostTarget).
		HeadersRegexp("Accept", JsonTypeRegex).
		Headers("Content-Type", JsonType).
		Methods("POST").
		Name(RoutePostTarget)
}