Add cursor and offset pagination. Add cursor for list ticket comments.

Author: pierce-m

fixture/GET/ticket_comments.json

@@ -22,5 +22,10 @@
 		  "attachments": [],
 		  "created_at": "2019-06-03T02:23:47Z"
 	  }
-  ]
+  ],
+  "meta": {
+    "has_more": true,
+    "after_cursor": "xxx",
+    "before_cursor": "yyy"
+  }
 }

zendesk/ticket_comment.go

@@ -10,7 +10,7 @@ import (
 // TicketCommentAPI is an interface containing all ticket comment related API methods
 type TicketCommentAPI interface {
 	CreateTicketComment(ctx context.Context, ticketID int64, ticketComment TicketComment) (TicketComment, error)
-	ListTicketComments(ctx context.Context, ticketID int64) ([]TicketComment, error)
+	ListTicketComments(ctx context.Context, ticketID int64, opts *CursorPagination) (*ListTicketCommentsResult, error)
 	MakeCommentPrivate(ctx context.Context, ticketID int64, ticketCommentID int64) error
 }
 
@@ -82,25 +82,37 @@ func (z *Client) CreateTicketComment(ctx context.Context, ticketID int64, ticket
 	return result, err
 }
 
+type ListTicketCommentsResult struct {
+	TicketComments []TicketComment      `json:"comments"`
+	Meta           CursorPaginationMeta `json:"meta"`
+}
+
 // ListTicketComments gets a list of comment for a specified ticket
 //
 // ref: https://developer.zendesk.com/rest_api/docs/support/ticket_comments#list-comments
-func (z *Client) ListTicketComments(ctx context.Context, ticketID int64) ([]TicketComment, error) {
-	var result struct {
-		TicketComments []TicketComment `json:"comments"`
+func (z *Client) ListTicketComments(ctx context.Context, ticketID int64, opts *CursorPagination) (*ListTicketCommentsResult, error) {
+	url := fmt.Sprintf("/tickets/%d/comments.json", ticketID)
+
+	var err error
+	if opts != nil {
+		url, err = addOptions(url, opts)
+		if err != nil {
+			return nil, err
+		}
 	}
 
-	body, err := z.get(ctx, fmt.Sprintf("/tickets/%d/comments.json", ticketID))
+	body, err := z.get(ctx, url)
 	if err != nil {
-		return []TicketComment{}, err
+		return nil, err
 	}
 
+	var result ListTicketCommentsResult
 	err = json.Unmarshal(body, &result)
 	if err != nil {
-		return []TicketComment{}, err
+		return nil, err
 	}
 
-	return result.TicketComments, err
+	return &result, err
 }
 
 // MakeCommentPrivate converts an existing ticket comment to an internal note that is not publicly viewable.

zendesk/ticket_comment_test.go

@@ -43,14 +43,26 @@ func TestListTicketComments(t *testing.T) {
 	client := newTestClient(mockAPI)
 	defer mockAPI.Close()
 
-	ticketComments, err := client.ListTicketComments(ctx, 2)
+	result, err := client.ListTicketComments(ctx, 2, nil)
 	if err != nil {
 		t.Fatalf("Failed to list ticket comments: %s", err)
 	}
 
 	expectedLength := 2
-	if len(ticketComments) != expectedLength {
-		t.Fatalf("Returned ticket comments does not have the expected length %d. Ticket comments length is %d", expectedLength, len(ticketComments))
+	if len(result.TicketComments) != expectedLength {
+		t.Fatalf("Returned ticket comments does not have the expected length %d. Ticket comments length is %d", expectedLength, len(result.TicketComments))
+	}
+
+	expectedPaginationMeta := CursorPaginationMeta{
+		HasMore:      true,
+		AfterCursor:  "xxx",
+		BeforeCursor: "yyy",
+	}
+
+	if result.Meta != expectedPaginationMeta {
+		t.Fatalf(`Failed to return correct cursor options.
+Expected: %+v
+Received: %+v`, expectedPaginationMeta, result.Meta)
 	}
 }
 

zendesk/zendesk.go

@@ -40,6 +40,54 @@ type (
 		Put(ctx context.Context, path string, data interface{}) ([]byte, error)
 		Delete(ctx context.Context, path string) error
 	}
+
+	// OffsetPagination contains options for using offset pagination.
+	// Many endpoints support cursor pagination, which is preferred as
+	// it is more performant on large datasets.
+	OffsetPagination struct {
+		// Page is the page number to request.
+		Page int `url:"page",omitempty`
+
+		// PerPage is the number of results desired on each page.
+		// Most endpoints support up to 100 records per page.
+		PerPage int `url:"per_page",omitempty`
+	}
+
+	// OffsetPaginationMeta contains next and previous page pointers.
+	OffsetPaginationMeta struct {
+		// NextPage is a link to the next page of results, nil if none left.
+		NextPage string `json:"next_page",omitempty`
+
+		// PreviousPage is a link to the previous page of results, nil if on first page.
+		PreviousPage string `json:"previous_page",omitempty`
+	}
+
+	// CursorPagination contains options for using cursor pagination.
+	// Cursor pagination is preferred where possible.
+	CursorPagination struct {
+		// PageSize sets the number of results per page.
+		// Most endpoints support up to 100 records per page.
+		PageSize int `url:"page[size]",omitempty`
+
+		// PageAfter provides the "next" cursor.
+		PageAfter string `url:"page[after]",omitempty`
+
+		// PageBefore provides the "previous" cursor.
+		PageBefore string `url:"page[before]",omitempty`
+	}
+
+	// CursorPaginationMeta contains information concerning how to fetch
+	// next and previous results, and if next results exist.
+	CursorPaginationMeta struct {
+		// HasMore is true if more results exist in the endpoint.
+		HasMore bool `json:"has_more",omitempty`
+
+		// AfterCursor contains the cursor of the next result set.
+		AfterCursor string `json:"after_cursor",omitempty`
+
+		// BeforeCursor contains the cursor of the previous result set.
+		BeforeCursor string `json:"before_cursor",omitempty`
+	}
 )
 
 // NewClient creates new Zendesk API client