71 |
72 |
73 |
74 | `
75 |
--------------------------------------------------------------------------------
/rest/middleware/cors_test.go:
--------------------------------------------------------------------------------
1 | package middleware
2 |
3 | import (
4 | "net/http"
5 | "net/http/httptest"
6 | "testing"
7 |
8 | "github.com/stretchr/testify/assert"
9 | )
10 |
11 | // Ensures that CORSMiddleware applies the headers needed for CORS when * is
12 | // present in the whitelist.
13 | func TestCORSMiddlewareAll(t *testing.T) {
14 | assert := assert.New(t)
15 | req, _ := http.NewRequest("GET", "http://example.com/foo", nil)
16 | req.Header.Set("Origin", "http://foo.com")
17 | req.Header.Set("Access-Control-Request-Headers", "def")
18 | w := httptest.NewRecorder()
19 | assert.Nil(NewCORSMiddleware([]string{"*"})(w, req))
20 |
21 | assert.Equal("http://foo.com", w.Header().Get("Access-Control-Allow-Origin"))
22 | assert.Equal("POST, GET, OPTIONS, PUT, DELETE", w.Header().Get("Access-Control-Allow-Methods"))
23 | assert.Equal([]string{"def"}, w.Header()["Access-Control-Allow-Headers"])
24 | assert.Equal([]string{"true"}, w.Header()["Access-Control-Allow-Credentials"])
25 | }
26 |
27 | // Ensures that CORSMiddleware applies the headers needed for CORS and respects
28 | // the origin whitelist.
29 | func TestCORSMiddlewareWhitelist(t *testing.T) {
30 | assert := assert.New(t)
31 | req, _ := http.NewRequest("GET", "http://example.com/foo", nil)
32 | req.Header.Set("Origin", "http://foo.wdesk.com")
33 | req.Header.Set("Access-Control-Request-Headers", "def")
34 | w := httptest.NewRecorder()
35 | middleware := NewCORSMiddleware([]string{"blah.wdesk.org", "*.wdesk.com"})
36 | assert.Nil(middleware(w, req))
37 |
38 | assert.Equal("http://foo.wdesk.com", w.Header().Get("Access-Control-Allow-Origin"))
39 | assert.Equal("POST, GET, OPTIONS, PUT, DELETE", w.Header().Get("Access-Control-Allow-Methods"))
40 | assert.Equal([]string{"def"}, w.Header()["Access-Control-Allow-Headers"])
41 | assert.Equal([]string{"true"}, w.Header()["Access-Control-Allow-Credentials"])
42 |
43 | // Mismatched origin
44 | req, _ = http.NewRequest("GET", "http://example.com/foo", nil)
45 | req.Header.Set("Origin", "http://baz.wdesk.org")
46 | req.Header.Set("Access-Control-Request-Headers", "def")
47 | w = httptest.NewRecorder()
48 | err := middleware(w, req)
49 | assert.NotNil(err)
50 | assert.Equal(http.StatusBadRequest, err.Code)
51 |
52 | assert.Equal("", w.Header().Get("Access-Control-Allow-Origin"))
53 | assert.Equal("", w.Header().Get("Access-Control-Allow-Methods"))
54 | assert.Nil(w.Header()["Access-Control-Allow-Headers"])
55 | assert.Nil(w.Header()["Access-Control-Allow-Credentials"])
56 | }
57 |
58 | // Ensures that CORSMiddleware returns a MiddlewareError with a 200 response
59 | // code.
60 | func TestCORSMiddlewareOptionsRequest(t *testing.T) {
61 | req, _ := http.NewRequest("OPTIONS", "http://example.com/foo", nil)
62 | req.Header.Set("Origin", "http://foo.com")
63 | w := httptest.NewRecorder()
64 | err := NewCORSMiddleware([]string{"foo.com"})(w, req)
65 | assert.Equal(t, http.StatusOK, err.Code)
66 | }
67 |
68 | // Ensures that CORSMiddleware doesn't return an error when a request is given
69 | // without an Origin header.
70 | func TestCORSMiddlewareNoOrigin(t *testing.T) {
71 | req, _ := http.NewRequest("GET", "http://example.com/foo", nil)
72 | w := httptest.NewRecorder()
73 | err := NewCORSMiddleware([]string{"blah.wdesk.org", "*.wdesk.com"})(w, req)
74 | assert.Nil(t, err)
75 | }
76 |
--------------------------------------------------------------------------------
/rest/example_ids_only_test.go:
--------------------------------------------------------------------------------
1 | /*
2 | Copyright 2014 - 2015 Workiva, LLC
3 |
4 | Licensed under the Apache License, Version 2.0 (the "License");
5 | you may not use this file except in compliance with the License.
6 | You may obtain a copy of the License at
7 |
8 | http://www.apache.org/licenses/LICENSE-2.0
9 |
10 | Unless required by applicable law or agreed to in writing, software
11 | distributed under the License is distributed on an "AS IS" BASIS,
12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | See the License for the specific language governing permissions and
14 | limitations under the License.
15 | */
16 |
17 | package rest
18 |
19 | import "strconv"
20 |
21 | // MyResource represents a domain model for which we want to perform CRUD
22 | // operations with. Endpoints can operate on any type of entity -- primitive,
23 | // struct, or composite -- so long as it is serializable (by default, this means
24 | // JSON-serializable via either MarshalJSON or JSON struct tags).
25 | type MyResource struct {
26 | ID int `json:"id"`
27 | Foobar string `json:"foobar"`
28 | }
29 |
30 | // MyResourceHandler implements the ResourceHandler interface. It specifies the
31 | // business logic for performing CRUD operations. BaseResourceHandler provides
32 | // stubs for each method if you only need to implement certain operations (as
33 | // this example illustrates).
34 | type MyResourceHandler struct {
35 | BaseResourceHandler
36 | }
37 |
38 | // ResourceName is used to identify what resource a handler corresponds to and
39 | // is used in the endpoint URLs, i.e. /api/:version/myresource.
40 | func (m MyResourceHandler) ResourceName() string {
41 | return "myresource"
42 | }
43 |
44 | // ReadResourceList is the logic that corresponds to reading multiple resources,
45 | // perhaps with specified query parameters accessed through the RequestContext.
46 | // This is mapped to GET /api/:version/myresource. Typically, this would make
47 | // some sort of database query to fetch the resources. It returns the slice of
48 | // results, a cursor (or empty) string, and error (or nil). In this example, we
49 | // illustrate how to use a query parameter to return only the IDs of our
50 | // resources.
51 | func (m MyResourceHandler) ReadResourceList(ctx RequestContext, limit int,
52 | cursor string, version string) ([]Resource, string, error) {
53 | // Make a database call here.
54 | resources := make([]Resource, 0, limit)
55 | resources = append(resources, &FooResource{ID: 1, Foobar: "hello"})
56 | resources = append(resources, &FooResource{ID: 2, Foobar: "world"})
57 |
58 | // ids_only is a query string parameter (i.e. /api/v1/myresource?ids_only=true).
59 | keysOnly, _ := strconv.ParseBool(ctx.ValueWithDefault("ids_only", "0").(string))
60 |
61 | if keysOnly {
62 | keys := make([]Resource, 0, len(resources))
63 | for _, resource := range resources {
64 | keys = append(keys, resource.(*FooResource).ID)
65 | }
66 | return keys, "", nil
67 | }
68 |
69 | return resources, "", nil
70 | }
71 |
72 | // This example shows how to implement a ResourceHandler which has an endpoint
73 | // for fetching multiple resources and, optionally, retrieving only their IDs.
74 | func Example_idsOnly() {
75 | api := NewAPI(NewConfiguration())
76 |
77 | // Call RegisterResourceHandler to wire up HelloWorldHandler.
78 | api.RegisterResourceHandler(MyResourceHandler{})
79 |
80 | // We're ready to hit our CRUD endpoints.
81 | api.Start(":8080")
82 | }
83 |
--------------------------------------------------------------------------------
/rest/serialize.go:
--------------------------------------------------------------------------------
1 | /*
2 | Copyright 2014 - 2015 Workiva, LLC
3 |
4 | Licensed under the Apache License, Version 2.0 (the "License");
5 | you may not use this file except in compliance with the License.
6 | You may obtain a copy of the License at
7 |
8 | http://www.apache.org/licenses/LICENSE-2.0
9 |
10 | Unless required by applicable law or agreed to in writing, software
11 | distributed under the License is distributed on an "AS IS" BASIS,
12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | See the License for the specific language governing permissions and
14 | limitations under the License.
15 | */
16 |
17 | package rest
18 |
19 | import (
20 | "encoding/json"
21 | "net/http"
22 | "reflect"
23 | )
24 |
25 | const (
26 | status = "status"
27 | reason = "reason"
28 | messages = "messages"
29 | result = "result"
30 | results = "results"
31 | next = "next"
32 | )
33 |
34 | // response is a data structure holding the serializable response body for a request and
35 | // HTTP status code. It should be created using NewResponse.
36 | type response struct {
37 | Payload Payload
38 | Status int
39 | }
40 |
41 | // ResponseSerializer is responsible for serializing REST responses and sending
42 | // them back to the client.
43 | type ResponseSerializer interface {
44 |
45 | // Serialize marshals a response payload into a byte slice to be sent over the wire.
46 | Serialize(Payload) ([]byte, error)
47 |
48 | // ContentType returns the MIME type of the response.
49 | ContentType() string
50 | }
51 |
52 | // jsonSerializer is an implementation of ResponseSerializer which serializes responses
53 | // as JSON.
54 | type jsonSerializer struct{}
55 |
56 | // Serialize marshals a response payload into a JSON byte slice to be sent over the wire.
57 | func (j jsonSerializer) Serialize(p Payload) ([]byte, error) {
58 | return json.Marshal(p)
59 | }
60 |
61 | // ContentType returns the JSON MIME type of the response.
62 | func (j jsonSerializer) ContentType() string {
63 | return "application/json"
64 | }
65 |
66 | // NewResponse constructs a new response struct containing the payload to send back.
67 | // It will either be a success or error response depending on the RequestContext.
68 | func NewResponse(ctx RequestContext) response {
69 | err := ctx.Error()
70 | if err != nil {
71 | return newErrorResponse(ctx)
72 | }
73 |
74 | return newSuccessResponse(ctx)
75 | }
76 |
77 | // newSuccessResponse constructs a new response struct containing a resource response.
78 | func newSuccessResponse(ctx RequestContext) response {
79 | r := ctx.Result()
80 | resultKey := result
81 | if r != nil && reflect.TypeOf(r).Kind() == reflect.Slice {
82 | resultKey = results
83 | }
84 |
85 | s := ctx.Status()
86 | response := response{Status: s}
87 |
88 | if s != http.StatusNoContent {
89 | payload := Payload{
90 | status: s,
91 | reason: http.StatusText(s),
92 | messages: ctx.Messages(),
93 | resultKey: r,
94 | }
95 |
96 | if nextURL, err := ctx.NextURL(); err == nil && nextURL != "" {
97 | payload[next] = nextURL
98 | }
99 |
100 | response.Payload = payload
101 | }
102 |
103 | return response
104 | }
105 |
106 | // newErrorResponse constructs a new response struct containing an error message.
107 | func newErrorResponse(ctx RequestContext) response {
108 | err := ctx.Error()
109 | s := http.StatusInternalServerError
110 | if restError, ok := err.(Error); ok {
111 | s = restError.Status()
112 | }
113 |
114 | payload := Payload{
115 | status: s,
116 | reason: http.StatusText(s),
117 | messages: ctx.Messages(),
118 | }
119 |
120 | response := response{
121 | Payload: payload,
122 | Status: s,
123 | }
124 |
125 | return response
126 | }
127 |
--------------------------------------------------------------------------------
/rest/example_middleware_test.go:
--------------------------------------------------------------------------------
1 | /*
2 | Copyright 2014 - 2015 Workiva, LLC
3 |
4 | Licensed under the Apache License, Version 2.0 (the "License");
5 | you may not use this file except in compliance with the License.
6 | You may obtain a copy of the License at
7 |
8 | http://www.apache.org/licenses/LICENSE-2.0
9 |
10 | Unless required by applicable law or agreed to in writing, software
11 | distributed under the License is distributed on an "AS IS" BASIS,
12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | See the License for the specific language governing permissions and
14 | limitations under the License.
15 | */
16 |
17 | package rest
18 |
19 | import (
20 | "errors"
21 | "fmt"
22 | "log"
23 | "net/http"
24 | )
25 |
26 | // MiddlewareResource represents a domain model for which we want to perform
27 | // CRUD operations with. Endpoints can operate on any type of entity --
28 | // primitive, struct, or composite -- so long as it is serializable (by default,
29 | // this means JSON-serializable via either MarshalJSON or JSON struct tags).
30 | type MiddlewareResource struct {
31 | ID int `json:"id"`
32 | Foobar string `json:"foobar"`
33 | }
34 |
35 | // MiddlewareHandler implements the ResourceHandler interface. It specifies the
36 | // business logic for performing CRUD operations. BaseResourceHandler provides
37 | // stubs for each method if you only need to implement certain operations (as
38 | // this example illustrates).
39 | type MiddlewareHandler struct {
40 | BaseResourceHandler
41 | }
42 |
43 | // ResourceName is used to identify what resource a handler corresponds to and
44 | // is used in the endpoint URLs, i.e. /api/:version/example.
45 | func (e MiddlewareHandler) ResourceName() string {
46 | return "example"
47 | }
48 |
49 | // Authenticate is logic that is used to authenticate requests to this
50 | // ResourceHandler. Returns nil if the request is authenticated or an error if
51 | // it is not.
52 | func (e MiddlewareHandler) Authenticate(r *http.Request) error {
53 | if r.Header.Get("Answer") != "42" {
54 | return errors.New("what is the answer?")
55 | }
56 | return nil
57 | }
58 |
59 | // ReadResource is the logic that corresponds to reading a single resource by
60 | // its ID at GET /api/:version/example/{id}. Typically, this would make some
61 | // sort of database query to load the resource. If the resource doesn't exist,
62 | // nil should be returned along with an appropriate error.
63 | func (e MiddlewareHandler) ReadResource(ctx RequestContext, id string, version string) (Resource, error) {
64 | // Make a database call here.
65 | if id == "42" {
66 | return &MiddlewareResource{ID: 42, Foobar: "hello world"}, nil
67 | }
68 | return nil, ResourceNotFound(fmt.Sprintf("No resource with id %s", id))
69 | }
70 |
71 | // ResourceHandler middleware is implemented as a closure which takes an
72 | // http.Handler and returns one.
73 | func HandlerMiddleware(next http.Handler) http.Handler {
74 | return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
75 | log.Printf("Request: %s", r.URL.String())
76 | next.ServeHTTP(w, r)
77 | })
78 | }
79 |
80 | // Global API middleware is implemented as a function which takes an
81 | // http.ResponseWriter and http.Request and returns a MiddlewareError if the
82 | // request should terminate.
83 | func GlobalMiddleware(w http.ResponseWriter, r *http.Request) *MiddlewareError {
84 | log.Println(r)
85 | return nil
86 | }
87 |
88 | // This example shows how to implement request middleware. ResourceHandlers
89 | // provide the Authenticate method which is used to authenticate requests, but
90 | // middleware allows you to insert additional authorization, logging, or other
91 | // AOP-style operations.
92 | func Example_middleware() {
93 | api := NewAPI(NewConfiguration())
94 |
95 | // Call RegisterResourceHandler to wire up MiddlewareHandler and apply middleware.
96 | api.RegisterResourceHandler(MiddlewareHandler{}, HandlerMiddleware)
97 |
98 | // Middleware provided to Start and StartTLS are invoked for every request handled
99 | // by the API.
100 | api.Start(":8080", GlobalMiddleware)
101 | }
102 |
--------------------------------------------------------------------------------
/rest/base_handler_test.go:
--------------------------------------------------------------------------------
1 | /*
2 | Copyright 2014 - 2015 Workiva, LLC
3 |
4 | Licensed under the Apache License, Version 2.0 (the "License");
5 | you may not use this file except in compliance with the License.
6 | You may obtain a copy of the License at
7 |
8 | http://www.apache.org/licenses/LICENSE-2.0
9 |
10 | Unless required by applicable law or agreed to in writing, software
11 | distributed under the License is distributed on an "AS IS" BASIS,
12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | See the License for the specific language governing permissions and
14 | limitations under the License.
15 | */
16 |
17 | package rest
18 |
19 | import (
20 | "testing"
21 |
22 | "github.com/stretchr/testify/assert"
23 | )
24 |
25 | type TestDefaultHandler struct {
26 | BaseResourceHandler
27 | }
28 |
29 | func (t TestDefaultHandler) ResourceName() string {
30 | return "foo"
31 | }
32 |
33 | // Ensures that CreateURI falls back to the correct default.
34 | func TestCreateURIDefault(t *testing.T) {
35 | assert := assert.New(t)
36 | proxy := resourceHandlerProxy{TestDefaultHandler{}}
37 |
38 | assert.Equal("/api/v{version:[^/]+}/foo", proxy.CreateURI())
39 | }
40 |
41 | // Ensures that ReadURI falls back to the correct default.
42 | func TestReadURIDefault(t *testing.T) {
43 | assert := assert.New(t)
44 | proxy := resourceHandlerProxy{TestDefaultHandler{}}
45 |
46 | assert.Equal("/api/v{version:[^/]+}/foo/{resource_id}", proxy.ReadURI())
47 | }
48 |
49 | // Ensures that ReadListURI falls back to the correct default.
50 | func TestReadListURIDefault(t *testing.T) {
51 | assert := assert.New(t)
52 | proxy := resourceHandlerProxy{TestDefaultHandler{}}
53 |
54 | assert.Equal("/api/v{version:[^/]+}/foo", proxy.ReadListURI())
55 | }
56 |
57 | // Ensures that UpdateURI falls back to the correct default.
58 | func TestUpdateURIDefault(t *testing.T) {
59 | assert := assert.New(t)
60 | proxy := resourceHandlerProxy{TestDefaultHandler{}}
61 |
62 | assert.Equal("/api/v{version:[^/]+}/foo/{resource_id}", proxy.UpdateURI())
63 | }
64 |
65 | // Ensures that DeleteURI falls back to the correct default.
66 | func TestDeleteURIDefault(t *testing.T) {
67 | assert := assert.New(t)
68 | proxy := resourceHandlerProxy{TestDefaultHandler{}}
69 |
70 | assert.Equal("/api/v{version:[^/]+}/foo/{resource_id}", proxy.DeleteURI())
71 | }
72 |
73 | type TestHandler struct {
74 | BaseResourceHandler
75 | }
76 |
77 | func (t TestHandler) ResourceName() string {
78 | return "foo"
79 | }
80 |
81 | func (t TestHandler) CreateURI() string {
82 | return "/api/{version}/create_foo"
83 | }
84 |
85 | func (t TestHandler) ReadURI() string {
86 | return "/api/{version}/read_foo/{resource_id}"
87 | }
88 |
89 | func (t TestHandler) ReadListURI() string {
90 | return "/api/{version}/read_foo"
91 | }
92 |
93 | func (t TestHandler) UpdateURI() string {
94 | return "/api/{version}/update_foo/{resource_id}"
95 | }
96 |
97 | func (t TestHandler) DeleteURI() string {
98 | return "/api/{version}/delete_foo/{resource_id}"
99 | }
100 |
101 | // Ensures that CreateURI returns the custom URI.
102 | func TestCreateURICustom(t *testing.T) {
103 | assert := assert.New(t)
104 | proxy := resourceHandlerProxy{TestHandler{}}
105 |
106 | assert.Equal("/api/{version}/create_foo", proxy.CreateURI())
107 | }
108 |
109 | // Ensures that ReadURI returns the custom URI.
110 | func TestReadURICustom(t *testing.T) {
111 | assert := assert.New(t)
112 | proxy := resourceHandlerProxy{TestHandler{}}
113 |
114 | assert.Equal("/api/{version}/read_foo/{resource_id}", proxy.ReadURI())
115 | }
116 |
117 | // Ensures that ReadListURI returns the custom URI.
118 | func TestReadListURICustom(t *testing.T) {
119 | assert := assert.New(t)
120 | proxy := resourceHandlerProxy{TestHandler{}}
121 |
122 | assert.Equal("/api/{version}/read_foo", proxy.ReadListURI())
123 | }
124 |
125 | // Ensures that UpdateURI returns the custom URI.
126 | func TestUpdateURICustom(t *testing.T) {
127 | assert := assert.New(t)
128 | proxy := resourceHandlerProxy{TestHandler{}}
129 |
130 | assert.Equal("/api/{version}/update_foo/{resource_id}", proxy.UpdateURI())
131 | }
132 |
133 | // Ensures that DeleteURI returns the custom URI.
134 | func TestDeleteURICustom(t *testing.T) {
135 | assert := assert.New(t)
136 | proxy := resourceHandlerProxy{TestHandler{}}
137 |
138 | assert.Equal("/api/{version}/delete_foo/{resource_id}", proxy.DeleteURI())
139 | }
140 |
--------------------------------------------------------------------------------
/rest/example_rules_test.go:
--------------------------------------------------------------------------------
1 | /*
2 | Copyright 2014 - 2015 Workiva, LLC
3 |
4 | Licensed under the Apache License, Version 2.0 (the "License");
5 | you may not use this file except in compliance with the License.
6 | You may obtain a copy of the License at
7 |
8 | http://www.apache.org/licenses/LICENSE-2.0
9 |
10 | Unless required by applicable law or agreed to in writing, software
11 | distributed under the License is distributed on an "AS IS" BASIS,
12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | See the License for the specific language governing permissions and
14 | limitations under the License.
15 | */
16 |
17 | package rest
18 |
19 | import (
20 | "fmt"
21 | "math/rand"
22 | )
23 |
24 | // ResourceWithSecret represents a domain model for which we want to perform
25 | // CRUD operations with. Endpoints can operate on any type of entity --
26 | // primitive, struct, or composite -- so long as it is serializable (by default,
27 | // this means JSON-serializable via either MarshalJSON or JSON struct tags). The
28 | // resource in this example has a field, "Secret", which we don't want to
29 | // include in REST responses.
30 | type ResourceWithSecret struct {
31 | ID int
32 | Foo string
33 | Nested FooResource
34 | Secret string
35 | }
36 |
37 | // ResourceWithSecretHandler implements the ResourceHandler interface. It
38 | // specifies the business logic for performing CRUD operations.
39 | // BaseResourceHandler provides stubs for each method if you only need to
40 | // implement certain operations (as this example illustrates).
41 | type ResourceWithSecretHandler struct {
42 | BaseResourceHandler
43 | }
44 |
45 | // ResourceName is used to identify what resource a handler corresponds to and
46 | // is used in the endpoint URLs, i.e. /api/:version/resource.
47 | func (r ResourceWithSecretHandler) ResourceName() string {
48 | return "resource"
49 | }
50 |
51 | // CreateResource is the logic that corresponds to creating a new resource at
52 | // POST /api/:version/resource. Typically, this would insert a record into a
53 | // database. It returns the newly created resource or an error if the create
54 | // failed. Because our Rules specify types, we can access the Payload data in a
55 | // type-safe way.
56 | func (r ResourceWithSecretHandler) CreateResource(ctx RequestContext, data Payload,
57 | version string) (Resource, error) {
58 | // Make a database call here.
59 | id := rand.Int()
60 | foo, _ := data.GetString("foo")
61 | created := &ResourceWithSecret{ID: id, Foo: foo, Secret: "secret"}
62 | return created, nil
63 | }
64 |
65 | // ReadResource is the logic that corresponds to reading a single resource by
66 | // its ID at GET /api/:version/resource/{id}. Typically, this would make some
67 | // sort of database query to load the resource. If the resource doesn't exist,
68 | // nil should be returned along with an appropriate error.
69 | func (r ResourceWithSecretHandler) ReadResource(ctx RequestContext, id string,
70 | version string) (Resource, error) {
71 | // Make a database call here.
72 | if id == "42" {
73 | return &ResourceWithSecret{
74 | ID: 42,
75 | Foo: "hello world",
76 | Secret: "keep it secret, keep it safe",
77 | }, nil
78 | }
79 | return nil, ResourceNotFound(fmt.Sprintf("No resource with id %s", id))
80 | }
81 |
82 | // Rules returns the resource rules to apply to incoming requests and outgoing
83 | // responses. The default behavior, seen in BaseResourceHandler, is to apply no
84 | // rules. Note that a Rule is not specified for the "Secret" field. This means
85 | // that field will not be included in the response. The "Type" field on a Rule
86 | // indicates the type the incoming data should be coerced to. If coercion fails,
87 | // an error indicating this will be sent back in the response. If no type is
88 | // specified, no coercion will be performed. Rules may also be nested. NewRules
89 | // is used to initialize Rules and associate them with the resource type using
90 | // the nil pointer. This allows Rule validation to occur at startup.
91 | func (r ResourceWithSecretHandler) Rules() Rules {
92 | return NewRules((*ResourceWithSecret)(nil),
93 | &Rule{
94 | Field: "ID",
95 | FieldAlias: "id",
96 | Type: Int,
97 | Versions: []string{"1, 2"},
98 | OutputOnly: true,
99 | },
100 | &Rule{
101 | Field: "Foo",
102 | FieldAlias: "f",
103 | Type: String,
104 | Versions: []string{"1"},
105 | Required: true,
106 | },
107 | &Rule{
108 | Field: "Foo",
109 | FieldAlias: "foo",
110 | Type: String,
111 | Versions: []string{"2"},
112 | Required: true,
113 | },
114 | &Rule{
115 | Field: "Nested",
116 | FieldAlias: "nested",
117 | Versions: []string{"2"},
118 | Rules: NewRules((*FooResource)(nil),
119 | &Rule{
120 | Field: "ID",
121 | FieldAlias: "id",
122 | Type: Int,
123 | OutputOnly: true,
124 | },
125 | &Rule{
126 | Field: "Foobar",
127 | FieldAlias: "foobar",
128 | Type: String,
129 | },
130 | ),
131 | },
132 | )
133 | }
134 |
135 | // This example shows how Rules are used to provide fine-grained control over
136 | // response input and output.
137 | func Example_rules() {
138 | api := NewAPI(NewConfiguration())
139 |
140 | // Call RegisterResourceHandler to wire up ResourceWithSecretHandler.
141 | api.RegisterResourceHandler(ResourceWithSecretHandler{})
142 |
143 | // We're ready to hit our CRUD endpoints.
144 | api.Start(":8080")
145 | }
146 |
--------------------------------------------------------------------------------
/rest/example_simple_crud_test.go:
--------------------------------------------------------------------------------
1 | /*
2 | Copyright 2014 - 2015 Workiva, LLC
3 |
4 | Licensed under the Apache License, Version 2.0 (the "License");
5 | you may not use this file except in compliance with the License.
6 | You may obtain a copy of the License at
7 |
8 | http://www.apache.org/licenses/LICENSE-2.0
9 |
10 | Unless required by applicable law or agreed to in writing, software
11 | distributed under the License is distributed on an "AS IS" BASIS,
12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | See the License for the specific language governing permissions and
14 | limitations under the License.
15 | */
16 |
17 | package rest
18 |
19 | import (
20 | "fmt"
21 | "math/rand"
22 | "net/http"
23 | "strconv"
24 | )
25 |
26 | // FooResource represents a domain model for which we want to perform CRUD
27 | // operations with. Endpoints can operate on any type of entity -- primitive,
28 | // struct, or composite -- so long as it is serializable (by default, this means
29 | // JSON-serializable via either MarshalJSON or JSON struct tags).
30 | type FooResource struct {
31 | ID int `json:"id"`
32 | Foobar string `json:"foobar"`
33 | }
34 |
35 | // FooHandler implements the ResourceHandler interface. It specifies the
36 | // business logic for performing CRUD operations.
37 | type FooHandler struct {
38 | BaseResourceHandler
39 | }
40 |
41 | // ResourceName is used to identify what resource a handler corresponds to and
42 | // is used in the endpoint URLs, i.e. /api/:version/foo.
43 | func (f FooHandler) ResourceName() string {
44 | return "foo"
45 | }
46 |
47 | // CreateResource is the logic that corresponds to creating a new resource at
48 | // POST /api/:version/foo. Typically, this would insert a record into a
49 | // database. It returns the newly created resource or an error if the create
50 | // failed.
51 | func (f FooHandler) CreateResource(ctx RequestContext, data Payload,
52 | version string) (Resource, error) {
53 | // Make a database call here.
54 | id := rand.Int()
55 | foobar, _ := data.GetString("foobar")
56 | created := &FooResource{ID: id, Foobar: foobar}
57 | return created, nil
58 | }
59 |
60 | // ReadResource is the logic that corresponds to reading a single resource by
61 | // its ID at GET /api/:version/foo/{id}. Typically, this would make some sort of
62 | // database query to load the resource. If the resource doesn't exist, nil
63 | // should be returned along with an appropriate error.
64 | func (f FooHandler) ReadResource(ctx RequestContext, id string,
65 | version string) (Resource, error) {
66 | // Make a database call here.
67 | if id == "42" {
68 | return &FooResource{ID: 42, Foobar: "hello world"}, nil
69 | }
70 | return nil, ResourceNotFound(fmt.Sprintf("No resource with id %s", id))
71 | }
72 |
73 | // ReadResourceList is the logic that corresponds to reading multiple resources,
74 | // perhaps with specified query parameters accessed through the RequestContext.
75 | // This is mapped to GET /api/:version/foo. Typically, this would make some sort
76 | // of database query to fetch the resources. It returns the slice of results, a
77 | // cursor (or empty) string, and error (or nil).
78 | func (f FooHandler) ReadResourceList(ctx RequestContext, limit int,
79 | cursor string, version string) ([]Resource, string, error) {
80 | // Make a database call here.
81 | resources := make([]Resource, 0, limit)
82 | resources = append(resources, &FooResource{ID: 1, Foobar: "hello"})
83 | resources = append(resources, &FooResource{ID: 2, Foobar: "world"})
84 | return resources, "", nil
85 | }
86 |
87 | // UpdateResource is the logic that corresponds to updating an existing resource
88 | // at PUT /api/:version/foo/{id}. Typically, this would make some sort of
89 | // database update call. It returns the updated resource or an error if the
90 | // update failed.
91 | func (f FooHandler) UpdateResource(ctx RequestContext, id string, data Payload,
92 | version string) (Resource, error) {
93 | // Make a database call here.
94 | updateID, _ := strconv.Atoi(id)
95 | foobar, _ := data.GetString("foobar")
96 | foo := &FooResource{ID: updateID, Foobar: foobar}
97 | return foo, nil
98 | }
99 |
100 | // DeleteResource is the logic that corresponds to deleting an existing resource
101 | // at DELETE /api/:version/foo/{id}. Typically, this would make some sort of
102 | // database delete call. It returns the deleted resource or an error if the
103 | // delete failed.
104 | func (f FooHandler) DeleteResource(ctx RequestContext, id string,
105 | version string) (Resource, error) {
106 | // Make a database call here.
107 | deleteID, _ := strconv.Atoi(id)
108 | foo := &FooResource{ID: deleteID, Foobar: "Goodbye world"}
109 | return foo, nil
110 | }
111 |
112 | // Authenticate is logic that is used to authenticate requests. The default
113 | // behavior of Authenticate, seen in BaseResourceHandler, always returns nil,
114 | // meaning all requests are authenticated. Returning an error means that the
115 | // request is unauthorized and any error message will be sent back with the
116 | // response.
117 | func (f FooHandler) Authenticate(r *http.Request) error {
118 | if secrets, ok := r.Header["Authorization"]; ok {
119 | if secrets[0] == "secret" {
120 | return nil
121 | }
122 | }
123 |
124 | return UnauthorizedRequest("You shall not pass")
125 | }
126 |
127 | // This example shows how to fully implement a basic ResourceHandler for
128 | // performing CRUD operations.
129 | func Example_simpleCrud() {
130 | api := NewAPI(NewConfiguration())
131 |
132 | // Call RegisterResourceHandler to wire up FooHandler.
133 | api.RegisterResourceHandler(FooHandler{})
134 |
135 | // We're ready to hit our CRUD endpoints.
136 | api.Start(":8080")
137 | }
138 |
--------------------------------------------------------------------------------
/documentation.md:
--------------------------------------------------------------------------------
1 | # Introducing go-rest
2 |
3 | The goal of go-rest is to provide a framework that makes it easy to build a flexible and (mostly) unopinionated REST API with little ceremony. More important, it offers a way to build stable, resource-oriented endpoints which are production-ready.
4 |
5 | At Workiva, we require standardized REST endpoints across all our services. This makes development more fluent and consumption easier and predictable, not just through syntax but also semantics. Many of our internal web services are written in Python, often running within Google App Engine. Within the past year, however, we've begun to build more services using Go—both on and off App Engine—because it lends itself well to many of the problems we're solving. As a result, we needed a way to build RESTful web services in a fashion similar to our Python ones.
6 |
7 | go-rest provides the tooling to build RESTful services rapidly and in a way that meets our internal API specification. Because it takes care of a lot of the boilerplate involved with building these types of services and offers some useful utilities, we're opening go-rest up to the open-source community. The remainder of this post explains go-rest in more detail, how it can be used to build REST APIs, and how we use it at Workiva.
8 |
9 | ## Composition and Extension
10 |
11 | go-rest is designed to be composable and pluggable. It makes no assumptions about your stack and doesn't care what libraries you're using or what your data model looks like. This is important to us at Workiva because it means we don't dictate down to developers what they need to use to solve their problems or force any artificial design constraints. Some services are running on App Engine and use its datastore. Others run off App Engine and don't necessarily use the datastore for persistence or entity modeling. go-rest is suited to either situation.
12 |
13 | Several pieces of go-rest are pluggable, meaning custom implementations can be provided. JSON is arguably the most common serialization format for REST APIs and it's what we use at Workiva, so the framework ships with JSON response serialization out of the box. Other response serializers, e.g. YAML or XML, can be provided.
14 |
15 | go-rest supports a notion of middleware, which are essentially just functions invoked on API requests. This has a wide range of application, ranging from authentication to logging and stats. For example, we use OAuth2 middleware to ensure authorized resource access.
16 |
17 | ## Building Stable APIs
18 |
19 | In order to provide fine-grained control over API input and output, go-rest uses a concept of REST rules. Rules provide schema validation and type coercion for request input and fine-grained control over response output. They can specify types in which input and output values should be coerced. If coercion fails, a meaningful error will be returned in the response. Rule validation is also built in to ensure the names and types specified on rules match up with their corresponding struct properties.
20 |
21 | Rules provide further control in that they can be used to discard values. For example, input fields which don't have corresponding rules can be ignored. Likewise, output fields with no respective rules will be dropped from the response.
22 |
23 | A useful property of stable REST APIs is endpoint versioning. go-rest provides support for this idea, facilitating different codepath execution based on API versions. Furthermore, rules can be specified with versions, allowing for control over input and output of versioned endpoints. This prevents new fields from leaking into old API versions.
24 |
25 | We use a [SemVer](http://semver.org/)-like approach to managing endpoint versions. REST rules allow us to accomplish this quite easily. If endpoint stability isn't a concern, you can neglect to specify rule versions or simply return full resource representations. This can be useful for rapid prototyping.
26 |
27 | ## Generating API Documentation
28 |
29 | Using the REST rules described above has a beneficial side effect: they provide a means of self-documentation. go-rest can use rules to generate documentation for your REST API. This documentation describes what endpoints are available and the payloads they expect, including what fields there are, which of these are required, and the expected types as well as what the response looks like. The beautiful thing is you get this all for *free*.
30 |
31 | We make extensive use of this documentation for several reasons. First, it acts as a contract for services. We write integration tests which verify our endpoints behave as they say they do. Second, they minimize unneeded communication between teams. We publish API documentation internally and people can look at this to understand how a service is used rather than going to the team directly. Third, and related to the first point, they promote building stable, high-quality APIs. By making this information visible, we expose the surface area of the API and document how it changes. This also forces teams to be held accountable for the services they provide.
32 |
33 | 
34 |
35 | ## Going Forward
36 |
37 | go-rest serves as a foundational piece for building production-quality REST APIs and is intended to fit into existing applications with ease. It lays much of the groundwork needed and allows for more frictionless development.
38 |
39 | REST rules provide a convenient way to maintain endpoints. While they offer a great deal of value already, there is more work to be done in order to make them even more useful. This includes pluggable type coercion, which would allow for conversion and validation of custom types. Another item is making the data validation more robust. Whether a custom-written or pre-existing library is used, this would enable semantic validation and custom validation logic. Currently, rules only provide type validation.
40 |
41 | Further work might include building a test-harness system to speed up unit and integration testing and improving documentation generation.
42 |
--------------------------------------------------------------------------------
/rest/handler_tpl.go:
--------------------------------------------------------------------------------
1 | /*
2 | Copyright 2014 - 2015 Workiva, LLC
3 |
4 | Licensed under the Apache License, Version 2.0 (the "License");
5 | you may not use this file except in compliance with the License.
6 | You may obtain a copy of the License at
7 |
8 | http://www.apache.org/licenses/LICENSE-2.0
9 |
10 | Unless required by applicable law or agreed to in writing, software
11 | distributed under the License is distributed on an "AS IS" BASIS,
12 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | See the License for the specific language governing permissions and
14 | limitations under the License.
15 | */
16 |
17 | package rest
18 |
19 | // handlerTemplate is the mustache template for the handler documentation.
20 | const handlerTemplate = `
21 |
22 |
23 |
24 | Documentation - {{resource}}
25 |
27 |
29 |
30 |
32 |
43 |
44 |
45 |
46 |