Merge pull request #292 from JinHuangAtZen/jin.huang/pagination-code-…

…template

Created code generator for OBP/CBP functions and iterator

.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
         path-to-profile: profile.cov
         flag-name: Go-${{ matrix.go-version }}
         parallel: true
-        ignore: zendesk/mock/client.go
+        ignore: zendesk/mock/client.go, zendesk/*_generated.go
 
   finalize:
     needs: test

CBPMigration.md

@@ -0,0 +1,92 @@
+# OBP to CBP migration
+
+Zendesk is [obsoleting](https://support.zendesk.com/hc/en-us/articles/4408846180634-Introducing-Pagination-Changes-Zendesk-API#h_01F7Y57A0G5M3R8JXGCQTBKVWA) Offset Based Pagination (OBP), it's recomended to start adopting Cursor Based Pagination (CBP). This SDK have created pagination Iterators to help facilite the change.
+
+To use the pagination iterator, start with `NewPaginationOptions()` function, it will return a `PaginationOptions` object, you can specify the default page size in `PageSize` variable. By default, `PageSize` is 100. Then you can call the `client.GetXXXXXIterator(ctx, ops)` to return an object pagination iterator, with the iterator, you can iterator through the objects with `HasMore()` and `GetNext()` until `HasMore` return `false`. 
+
+```go
+ops := NewPaginationOptions()
+// ops.PageSize = 50 // PageSize can be set to 50
+it := client.GetTicketsIterator(ctx, ops)
+for it.HasMore() {
+    tickets, err := it.GetNext()
+    if err == nil {
+        for _, ticket := range tickets {
+            println(ticket.Subject)
+        }
+    }
+}
+```
+
+If the API endpoint requires more options like organization ID, it can be set into the `Id` attribute like below example:
+
+```go
+ops := NewPaginationOptions()
+ops.Sort = "updated_at"
+ops.PageSize = 10
+ops.Id = 360363695492
+it := client.GetOrganizationTicketsIterator(ctx, ops)
+
+for it.HasMore() {
+    tickets, err := it.GetNext()
+    if err == nil {
+        for _, ticket := range tickets {
+            println(ticket.Subject)
+        }
+    }
+}
+```
+
+For any API specific parameters, they are predefined in the `CommonOptions` struct, we can set these attributes in the `PaginationOptions` object. 
+If new attributes are introduced to any existing or new API endpoints, it can be added into this struct.
+
+```go
+type CommonOptions struct {
+	Active        bool     `url:"active,omitempty"`
+	Role          string   `url:"role,omitempty"`
+	Roles         []string `url:"role[],omitempty"`
+	PermissionSet int64    `url:"permission_set,omitempty"`
+
+	// SortBy can take "assignee", "assignee.name", "created_at", "group", "id",
+	// "locale", "requester", "requester.name", "status", "subject", "updated_at"
+	SortBy string `url:"sort_by,omitempty"`
+
+	// SortOrder can take "asc" or "desc"
+	SortOrder      string `url:"sort_order,omitempty"`
+	Sort           string `url:"sort,omitempty"`
+	Id             int64
+	GroupID        int64 `json:"group_id,omitempty" url:"group_id,omitempty"`
+	UserID         int64 `json:"user_id,omitempty" url:"user_id,omitempty"`
+	OrganizationID int64 `json:"organization_id,omitempty" url:"organization_id,omitempty"`
+
+	Access            string `json:"access"`
+	Category          int    `json:"category"`
+	Include           string `json:"include" url:"include,omitempty"`
+	OnlyViewable      bool   `json:"only_viewable"`
+	Query             string `url:"query"`
+	EndUserVisible    bool   `url:"end_user_visible,omitempty"`
+	FallbackToDefault bool   `url:"fallback_to_default,omitempty"`
+	AssociatedToBrand bool   `url:"associated_to_brand,omitempty"`
+	CategoryID        string `url:"category_id,omitempty"`
+
+	IncludeInlineImages string `url:"include_inline_images,omitempty"`
+}
+```
+
+## To regenerate CBP(Cursor Based Pagination), OBP(Offset Based Pagination) helper function and Iterators
+
+If a new API endpoint supports CBP, add a new element to the funcData in script/codegen/main.go file like this:
+
+```go
+{
+    FuncName:    "Automations",
+    ObjectName:  "Automation",
+    ApiEndpoint: "/automation.json",
+    JsonName:    "automations",
+    FileName:    "automation",
+},
+```
+
+should use the script to generate the helper functions and the iterator
+`go run script/codegen/main.go`
+

README.md

@@ -1,4 +1,5 @@
 # go-zendesk
+
 [![Actions Status](https://github.com/nukosuke/go-zendesk/workflows/CI/badge.svg)](https://github.com/nukosuke/go-zendesk/actions)
 [![Build status](https://ci.appveyor.com/api/projects/status/ce4p1mswjkdftv6o/branch/master?svg=true)](https://ci.appveyor.com/project/nukosuke/go-zendesk/branch/master)
 [![Coverage Status](https://coveralls.io/repos/github/nukosuke/go-zendesk/badge.svg?branch=master)](https://coveralls.io/github/nukosuke/go-zendesk?branch=master)
@@ -12,7 +13,7 @@ Zendesk API client library for Go
 
 ## Installation
 
-``` shell
+```shell
 $ go get github.com/nukosuke/go-zendesk
 ```
 
@@ -48,14 +49,18 @@ func main() {
 ```
 
 ## Want to mock API?
+
 go-zendesk has a [mock package](https://pkg.go.dev/github.com/nukosuke/go-zendesk/zendesk/mock) generated by [golang/mock](https://github.com/golang/mock).
 You can simulate the response from Zendesk API with it.
 
 ## To regenerate the mock client
 
 `go generate ./...`
 
+## Zendesk [OBP(Offset Based Pagination) to CBP(Cursor Based Pagination) migration guide](CBPMigration.md)
+
 ## Maintainer
+
 - [nukosuke](https://github.com/nukosuke)
 
 ## License
@@ -64,5 +69,4 @@ MIT License.
 
 See the file [LICENSE](./LICENSE).
 
-
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fnukosuke%2Fgo-zendesk.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fnukosuke%2Fgo-zendesk?ref=badge_large)