Merge branch 'omani-master'

Author: rs

README.md

@@ -413,7 +413,6 @@ Content-Length: 257
 Content-Type: application/json
 Date: Mon, 27 Jul 2015 19:51:46 GMT
 Vary: Origin
-X-Page: 1
 X-Total: 1
 
 [
@@ -439,7 +438,6 @@ Content-Length: 257
 Content-Type: application/json
 Date: Mon, 27 Jul 2015 19:51:46 GMT
 Vary: Origin
-X-Page: 1
 X-Total: 1
 
 [
@@ -848,14 +846,29 @@ You can invert the operator by passing `false`.
 
 ## Sorting
 
-Sorting is of resource items is defined throught the `sort` query-string parameter. The `sort` value is a list of resource's fields separated by comas (`,`). To invert a field's sort, you can prefix its name with a minus (`-`) character.
+Sorting of resource items is defined through the `sort` query-string parameter. The `sort` value is a list of resource's fields separated by comas (`,`). To invert a field's sort, you can prefix its name with a minus (`-`) character.
 
 To use a resource field with the `sort` parameter, the field must be defined on the resource and the `Sortable` field property must be set to `true`. You may want to ensure the backend database has this field indexed when enabled.
 
 Here we sort the result by ascending quantity and descending date:
 
 	/posts?sort=quantity,-created
 
+## Skipping
+
+Skipping of resource items is defined through the `skip` query-string parameter. The `skip` value is a positive integer defining the number of items to skip when querying for items.
+
+To use a resource field with the `skip` parameter, the field must be defined on the resource.
+
+Skip the first 10 items of the result:
+
+    /posts?skip=10
+
+Return the first 2 items after skipping the first 10 of the result:
+
+    /posts?skip=10&limit=2
+Note that `skip` can't be used with pagination.
+
 ## Field Selection
 
 REST APIs tend to grow over time. Resources get more and more fields to fulfill the needs for new features. But each time fields are added, all existing API clients automatically gets the additional cost. This tend to lead to huge wast of bandwidth and added latency due to the transfer of unnecessary data.
@@ -999,13 +1012,13 @@ $ http -b :8080/api/users/ar6eimekj5lfktka9mt0/posts \
 
 In the above example, the `user` field is a reference on the `users` resource. REST Layer did fetch the user referenced by the post and embedded the requested sub-fields (`id` and `name`). Same for `comments`: `comments` is set as a sub-resource of the `posts` resource. With this syntax, it's easy to get the last 10 comments on the post in the same REST request. For each of those comment, we asked to embed the `user` field referenced resource with `id` and `name` fields again.
 
-Notice the `sort` and `limit` parameters passed to the `comments` field. Those are field parameter automatically exposed by connections to let you control the embedded list order, filter and pagination. You can use `sort`, `filter`, `page` and `limit` parameters with those field with the same syntax as their top level query-string parameter counterpart.
+Notice the `sort` and `limit` parameters passed to the `comments` field. Those are field parameter automatically exposed by connections to let you control the embedded list order, filter and pagination. You can use `sort`, `filter`, `skip`, `page` and `limit` parameters with those field with the same syntax as their top level query-string parameter counterpart.
 
 Such request can quickly generate a lot of queries on the storage handler. To ensure a fast response time, REST layer tries to coalesce those storage requests and to execute them concurrently whenever possible.
 
 ## Pagination
 
-Pagination is supported on collection URLs using `page` and `limit` query-string parameters. If you don't define a default pagination limit using `PaginationDefaultLimit` resource configuration parameter, the resource won't be paginated until you provide the `limit` query-string parameter.
+Pagination is supported on collection URLs using `skip`, `page` and `limit` query-string parameters. If you don't define a default pagination limit using `PaginationDefaultLimit` resource configuration parameter, the resource won't be paginated until you provide the `limit` query-string parameter.
 
 If your collections are large enough, failing to define a reasonable `PaginationDefaultLimit` parameter may quickly render your API unusable.
 
@@ -1289,7 +1302,7 @@ A resource storage handler is easy to write though. Some handlers for [popular d
 
 ```go
 type Storer interface {
-	Find(ctx context.Context, lookup *resource.Lookup, page, perPage int) (*resource.ItemList, error)
+	Find(ctx context.Context, lookup *resource.Lookup, offset, limit int) (*resource.ItemList, error)
 	Insert(ctx context.Context, items []*resource.Item) error
 	Update(ctx context.Context, item *resource.Item, original *resource.Item) error
 	Delete(ctx context.Context, item *resource.Item) error
@@ -1349,11 +1362,11 @@ type myResponseFormatter struct {
 
 // Add a wrapper around the list with pagination info
 func (r myResponseFormatter) FormatList(ctx context.Context, headers http.Header, l *resource.ItemList, skipBody bool) (context.Context, interface{}) {
-	ctx, data := r.DefaultResponseSender.FormatList(ctx, headers, l, skipBody)
+	ctx, data := r.DefaultResponseFormatter.FormatList(ctx, headers, l, skipBody)
 	return ctx, map[string]interface{}{
 		"meta": map[string]int{
-			"total": l.Total,
-			"page":  l.Page,
+			"offset": l.Offset,
+			"total":  l.Total,
 		},
 		"list": data,
 	}
@@ -1364,7 +1377,7 @@ func (r myResponseFormatter) FormatList(ctx context.Context, headers http.Header
 
 In parallel of the REST API handler, REST Layer is also able to handle GraphQL queries (mutation will come later). GraphQL is a query language created by Facebook which provides a common interface fetch and manipulate data. REST Layer's GraphQL handler is able to read a [resource.Index](https://godoc.org/github.com/rs/rest-layer/resource#Index) and create a corresponding GraphQL schema.
 
-GraphQL doesn't expose resources directly, but queries. REST Layer take all the resources defined at the root of the `resource.Index` and create two GraphQL queries for each one. On query is just the name of the endpoint, so `/users` would result in `users` and another is the name of the endpoint suffixed with `List`, as `usersList`. The item queries takes an `id` parameter and the list queries take `page`, `limit`, `filter` and `sort` parameters. All sub-resources are accessible using GraphQL sub-selection syntax.
+GraphQL doesn't expose resources directly, but queries. REST Layer take all the resources defined at the root of the `resource.Index` and create two GraphQL queries for each one. On query is just the name of the endpoint, so `/users` would result in `users` and another is the name of the endpoint suffixed with `List`, as `usersList`. The item queries takes an `id` parameter and the list queries take `skip`, `page`, `limit`, `filter` and `sort` parameters. All sub-resources are accessible using GraphQL sub-selection syntax.
 
 If you resource defines aliases, some additional GraphQL queris are exposes with their name constructed as the name of the resource suffixed with the name of the alias with a capital. So for `users` with an alias `admin`, the query would be `usersAdmin`.
 

examples/auth-jwt/main.go

@@ -93,7 +93,7 @@ type AuthResourceHook struct {
 }
 
 // OnFind implements resource.FindEventHandler interface
-func (a AuthResourceHook) OnFind(ctx context.Context, lookup *resource.Lookup, page, perPage int) error {
+func (a AuthResourceHook) OnFind(ctx context.Context, lookup *resource.Lookup, offset, limit int) error {
 	// Reject unauthorized users
 	user, found := UserFromContext(ctx)
 	if !found {

examples/auth/main.go

@@ -77,7 +77,7 @@ type AuthResourceHook struct {
 }
 
 // OnFind implements resource.FindEventHandler interface
-func (a AuthResourceHook) OnFind(ctx context.Context, lookup *resource.Lookup, page, perPage int) error {
+func (a AuthResourceHook) OnFind(ctx context.Context, lookup *resource.Lookup, offset, limit int) error {
 	// Reject unauthorized users
 	user, found := UserFromContext(ctx)
 	if !found {

graphql/functional_test.go

@@ -196,7 +196,7 @@ func TestHandler(t *testing.T) {
 	r, _ = http.NewRequest("GET", "/?query={posts(id:\"ar5qrgukj5l7a6eq2ps0\"){id,meta{title},followers(limit:2){user{id,name}}}}", nil)
 	s, b = performRequest(gql, r)
 	assert.Equal(t, 200, s)
-	assert.Equal(t, "{\"data\":{\"posts\":{\"followers\":[{\"user\":{\"id\":\"fan1\",\"name\":\"Fan 1\"}},{\"user\":{\"id\":\"fan2\",\"name\":\"Fan 2\"}},{\"user\":{\"id\":\"fan3\",\"name\":\"Fan 3\"}}],\"id\":\"ar5qrgukj5l7a6eq2ps0\",\"meta\":{\"title\":\"First Post\"}}}}\n", b)
+	assert.Equal(t, "{\"data\":{\"posts\":{\"followers\":[{\"user\":{\"id\":\"fan1\",\"name\":\"Fan 1\"}},{\"user\":{\"id\":\"fan2\",\"name\":\"Fan 2\"}}],\"id\":\"ar5qrgukj5l7a6eq2ps0\",\"meta\":{\"title\":\"First Post\"}}}}\n", b)
 
 	r, _ = http.NewRequest("POST", "/", bytes.NewBufferString("{postsList{id,thumb_s_url:thumbnail_url(height:80)}}"))
 	s, b = performRequest(gql, r)

graphql/query.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"log"
 	"net/url"
-	"strconv"
 	"strings"
 
 	"github.com/graphql-go/graphql"
@@ -63,6 +62,9 @@ func (t types) getGetQuery(idx resource.Index, r *resource.Resource) *graphql.Fi
 }
 
 var listArgs = graphql.FieldConfigArgument{
+	"skip": &graphql.ArgumentConfig{
+		Type: graphql.Int,
+	},
 	"page": &graphql.ArgumentConfig{
 		Type: graphql.Int,
 	},
@@ -77,30 +79,28 @@ var listArgs = graphql.FieldConfigArgument{
 	},
 }
 
-func listParamResolver(r *resource.Resource, p graphql.ResolveParams, params url.Values) (lookup *resource.Lookup, page int, perPage int, err error) {
-	page = 1
-	// Default value on non HEAD request for perPage is -1 (pagination disabled)
-	perPage = -1
+func listParamResolver(r *resource.Resource, p graphql.ResolveParams, params url.Values) (lookup *resource.Lookup, offset int, limit int, err error) {
+	skip := 0
+	page := 1
+	// Default value on non HEAD request for limit is -1 (pagination disabled)
+	limit = -1
+
 	if l := r.Conf().PaginationDefaultLimit; l > 0 {
-		perPage = l
+		limit = l
 	}
-	if p, ok := p.Args["page"].(string); ok && p != "" {
-		i, err := strconv.ParseUint(p, 10, 32)
-		if err != nil {
-			return nil, 0, 0, errors.New("invalid `limit` parameter")
-		}
-		page = int(i)
+	if i, ok := p.Args["skip"].(int); ok && i >= 0 {
+		skip = i
 	}
-	if l, ok := p.Args["limit"].(string); ok && l != "" {
-		i, err := strconv.ParseUint(l, 10, 32)
-		if err != nil {
-			return nil, 0, 0, errors.New("invalid `limit` parameter")
-		}
-		perPage = int(i)
+	if i, ok := p.Args["page"].(int); ok && i > 0 && i < 1000 {
+		page = i
+	}
+	if i, ok := p.Args["limit"].(int); ok && i >= 0 && i < 1000 {
+		limit = i
 	}
-	if perPage == -1 && page != 1 {
+	if page != 1 && limit == -1 {
 		return nil, 0, 0, errors.New("cannot use `page' parameter with no `limit' paramter on a resource with no default pagination size")
 	}
+	offset = (page-1)*limit + skip
 	lookup = resource.NewLookup()
 	if sort, ok := p.Args["sort"].(string); ok && sort != "" {
 		if err := lookup.SetSort(sort, r.Validator()); err != nil {
@@ -128,11 +128,11 @@ func (t types) getListQuery(idx resource.Index, r *resource.Resource, params url
 		Type:        graphql.NewList(t.getObjectType(idx, r)),
 		Args:        listArgs,
 		Resolve: func(p graphql.ResolveParams) (interface{}, error) {
-			lookup, page, perPage, err := listParamResolver(r, p, params)
+			lookup, offset, limit, err := listParamResolver(r, p, params)
 			if err != nil {
 				return nil, err
 			}
-			list, err := r.Find(p.Context, lookup, page, perPage)
+			list, err := r.Find(p.Context, lookup, offset, limit)
 			if err != nil {
 				return nil, err
 			}

graphql/types.go

@@ -87,7 +87,7 @@ func getSubResourceResolver(r *resource.Resource) graphql.FieldResolveFn {
 		if !ok {
 			return nil, nil
 		}
-		lookup, page, perPage, err := listParamResolver(r, p, nil)
+		lookup, offset, limit, err := listParamResolver(r, p, nil)
 		if err != nil {
 			return nil, err
 		}
@@ -98,7 +98,7 @@ func getSubResourceResolver(r *resource.Resource) graphql.FieldResolveFn {
 				Value: parent["id"],
 			},
 		})
-		list, err := r.Find(p.Context, lookup, page, perPage)
+		list, err := r.Find(p.Context, lookup, offset, limit)
 		if err != nil {
 			return nil, err
 		}

resource/hook.go

@@ -9,15 +9,15 @@ import (
 // want to be called before a find is performed on a resource. This interface is
 // to be used with resource.Use() method.
 type FindEventHandler interface {
-	OnFind(ctx context.Context, lookup *Lookup, page, perPage int) error
+	OnFind(ctx context.Context, lookup *Lookup, offset, limit int) error
 }
 
 // FindEventHandlerFunc converts a function into a FindEventHandler.
-type FindEventHandlerFunc func(ctx context.Context, lookup *Lookup, page, perPage int) error
+type FindEventHandlerFunc func(ctx context.Context, lookup *Lookup, offset, limit int) error
 
 // OnFind implements FindEventHandler
-func (e FindEventHandlerFunc) OnFind(ctx context.Context, lookup *Lookup, page, perPage int) error {
-	return e(ctx, lookup, page, perPage)
+func (e FindEventHandlerFunc) OnFind(ctx context.Context, lookup *Lookup, offset, limit int) error {
+	return e(ctx, lookup, offset, limit)
 }
 
 // FoundEventHandler is an interface to be implemented by an event handler that
@@ -256,9 +256,9 @@ func (h *eventHandler) use(e interface{}) error {
 	return nil
 }
 
-func (h *eventHandler) onFind(ctx context.Context, lookup *Lookup, page, perPage int) error {
+func (h *eventHandler) onFind(ctx context.Context, lookup *Lookup, offset, limit int) error {
 	for _, e := range h.onFindH {
-		if err := e.OnFind(ctx, lookup, page, perPage); err != nil {
+		if err := e.OnFind(ctx, lookup, offset, limit); err != nil {
 			return err
 		}
 	}

resource/hook_test.go

@@ -11,7 +11,7 @@ import (
 func TestHookUseFind(t *testing.T) {
 	h := eventHandler{}
 	called := false
-	err := h.use(FindEventHandlerFunc(func(ctx context.Context, lookup *Lookup, page, perPage int) error {
+	err := h.use(FindEventHandlerFunc(func(ctx context.Context, lookup *Lookup, offset, limit int) error {
 		called = true
 		return nil
 	}))
@@ -31,7 +31,7 @@ func TestHookUseFind(t *testing.T) {
 	err = h.onFind(nil, nil, 0, 0)
 	assert.True(t, called)
 
-	err = h.use(FindEventHandlerFunc(func(ctx context.Context, lookup *Lookup, page, perPage int) error {
+	err = h.use(FindEventHandlerFunc(func(ctx context.Context, lookup *Lookup, offset, limit int) error {
 		return errors.New("error")
 	}))
 	assert.NoError(t, err)

resource/item.go

@@ -27,8 +27,10 @@ type ItemList struct {
 	// Total defines the total number of items in the collection matching the current
 	// context. If the storage handler cannot compute this value, -1 is set.
 	Total int
-	// Page is the current page represented by this ItemList.
-	Page int
+	// Offset is the index of the first item of the list in the global collection.
+	Offset int
+	// Limit is the max number of items requested.
+	Limit int
 	// Items is the list of items contained in the current page given the current
 	// context.
 	Items []*Item

resource/resource.go

@@ -156,6 +156,12 @@ func (r *Resource) Bind(name, field string, s schema.Schema, h Storer, c Conf) *
 			path: "." + name,
 		},
 		Params: schema.Params{
+			"skip": schema.Param{
+				Description: "The number of items to skip",
+				Validator: schema.Integer{
+					Boundaries: &schema.Boundaries{Min: 0},
+				},
+			},
 			"page": schema.Param{
 				Description: "The page number",
 				Validator: schema.Integer{
@@ -305,22 +311,22 @@ func (r *Resource) MultiGet(ctx context.Context, ids []interface{}) (items []*It
 }
 
 // Find implements Storer interface
-func (r *Resource) Find(ctx context.Context, lookup *Lookup, page, perPage int) (list *ItemList, err error) {
+func (r *Resource) Find(ctx context.Context, lookup *Lookup, offset, limit int) (list *ItemList, err error) {
 	if LoggerLevel <= LogLevelDebug && Logger != nil {
 		defer func(t time.Time) {
 			found := -1
 			if list != nil {
 				found = len(list.Items)
 			}
-			Logger(ctx, LogLevelDebug, fmt.Sprintf("%s.Find(..., %d, %d)", r.path, page, perPage), map[string]interface{}{
+			Logger(ctx, LogLevelDebug, fmt.Sprintf("%s.Find(..., %d, %d)", r.path, offset, limit), map[string]interface{}{
 				"duration": time.Since(t),
 				"found":    found,
 				"error":    err,
 			})
 		}(time.Now())
 	}
-	if err = r.hooks.onFind(ctx, lookup, page, perPage); err == nil {
-		list, err = r.storage.Find(ctx, lookup, page, perPage)
+	if err = r.hooks.onFind(ctx, lookup, offset, limit); err == nil {
+		list, err = r.storage.Find(ctx, lookup, offset, limit)
 	}
 	r.hooks.onFound(ctx, lookup, &list, &err)
 	return