api.go 2.7 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192
  1. /*
  2. The Kurz Web API exposes HTTP routes for JSON clients, route names to access them, and types for the requests and responses.
  3. - GET "/<short>" : resolve a short URL
  4. - Handler: handleGetShort()
  5. - Success: 307 to matching target URL
  6. - Client request incorrect: 400
  7. - Short not yet defined: 404 no matching target
  8. - Target blocked for permission reasons: 403
  9. - Target legally censored: 451
  10. - Server failure: 50*
  11. - POST "/" with <target>: create a short URL from a target URL
  12. - Handler: handlePostTarget()
  13. - Success: 201 with <new short>
  14. - Already existing short: 409 with <existing short>
  15. - Target blocked for permission reasons: 403
  16. - Target legally censored: 451
  17. - Server failure: 50*
  18. Code 451 MAY be replaced by 403, for example when legal censorship includes a
  19. gag order, super-injunction (UK), National security letter (US) or similar
  20. mechanisms.
  21. These routes are exposed by running SetupRoutes(listenAddress), which is enough to
  22. configure the Kurz domain API. Be sure to also configure the domain SPI to have
  23. a complete application.
  24. */
  25. package api
  26. import (
  27. "github.com/gorilla/mux"
  28. "github.com/nicksnyder/go-i18n/v2/i18n"
  29. "net/http"
  30. "net/url"
  31. )
  32. // Short is the type of responses provided by the Web API from a target.
  33. type Short struct {
  34. Short string `json:"short"`
  35. }
  36. // Target is the type of requests accepted by the Web API for target submissions.
  37. type Target struct {
  38. Target string `json:"target"`
  39. }
  40. // Route names.
  41. const (
  42. RouteGetShort = "kurz.api.get_short"
  43. RoutePostTarget = "kurz.api.post_target"
  44. )
  45. // Content types.
  46. const (
  47. // JsonType is the MIME JSON type.
  48. JsonType = "application/json"
  49. JsonTypeHeader = JsonType + "; charset=utf-8"
  50. // JsonTypeRegex is a regex matching the MIME JSON type anywhere
  51. JsonTypeRegex = JsonType
  52. )
  53. // SetupRoutes() configures Web API routes on the passed mux.Router.
  54. func SetupRoutes(router *mux.Router) {
  55. // BUG(fgm): improve Accept header matchers once https://github.com/golang/go/issues/19307 is completed.
  56. router.HandleFunc("/{short}", handleGetShort).
  57. HeadersRegexp("Accept", JsonTypeRegex).
  58. Methods("GET", "HEAD").
  59. Name(RouteGetShort)
  60. router.HandleFunc("/", handlePostTarget).
  61. HeadersRegexp("Accept", JsonTypeRegex).
  62. Headers("Content-Type", JsonType).
  63. Methods("POST").
  64. Name(RoutePostTarget)
  65. }
  66. func URLFromRoute(name string, args map[string]string) url.URL {
  67. return url.URL{}
  68. }
  69. // getLocalizer is a helper method to return the localizer in a request context, or nil if none is found.
  70. func getLocalizer(r *http.Request) *i18n.Localizer {
  71. iLocalizer := r.Context().Value("localizer")
  72. var localizer *i18n.Localizer
  73. if iLocalizer != nil {
  74. localizer = iLocalizer.(*i18n.Localizer)
  75. } else {
  76. localizer = nil
  77. }
  78. return localizer
  79. }