Generalize list header for API

CONTRIBUTING.md

@@ -207,6 +207,10 @@ In general, HTTP methods are chosen as follows:
 
 An endpoint which changes/edits an object expects all fields to be optional (except ones to identify the object, which are required).
 
+### Endpoints returning lists should
+ * support pagination (`page` & `limit` options in query)
+ * add `X-Total-Count` header ([example](https://github.com/go-gitea/gitea/blob/e76f8cac9a2ba727bec6b5beab2496be9dafabef/routers/api/v1/repo/issue.go#L445))
+
 
 ## Developer Certificate of Origin (DCO)
 

models/notification.go

@@ -125,6 +125,11 @@ func GetNotifications(opts *FindNotificationOptions) (NotificationList, error) {
 	return getNotifications(x, opts)
 }
 
+// CountNotifications count all notifications that fit to the given options and ignore pagination.
+func CountNotifications(opts *FindNotificationOptions) (int64, error) {
+	return x.Where(opts.ToCond()).Count(&Notification{})
+}
+
 // CreateRepoTransferNotification creates  notification for the user a repository was transferred to
 func CreateRepoTransferNotification(doer, newOwner *User, repo *Repository) error {
 	sess := x.NewSession()

models/token.go

@@ -122,6 +122,15 @@ func UpdateAccessToken(t *AccessToken) error {
 	return err
 }
 
+// CountAccessTokens count access tokens belongs to given user by options
+func CountAccessTokens(opts ListAccessTokensOptions) (int64, error) {
+	sess := x.Where("uid=?", opts.UserID)
+	if len(opts.Name) != 0 {
+		sess = sess.Where("name=?", opts.Name)
+	}
+	return sess.Count(&AccessToken{})
+}
+
 // DeleteAccessTokenByID deletes access token by given ID.
 func DeleteAccessTokenByID(id, userID int64) error {
 	cnt, err := x.ID(id).Delete(&AccessToken{

routers/api/v1/admin/cron.go

@@ -5,12 +5,14 @@
 package admin
 
 import (
+	"fmt"
 	"net/http"
 
 	"code.gitea.io/gitea/modules/context"
 	"code.gitea.io/gitea/modules/cron"
 	"code.gitea.io/gitea/modules/log"
 	"code.gitea.io/gitea/modules/structs"
+	"code.gitea.io/gitea/modules/util"
 	"code.gitea.io/gitea/routers/api/v1/utils"
 )
 
@@ -36,12 +38,10 @@ func ListCronTasks(ctx *context.APIContext) {
 	//   "403":
 	//     "$ref": "#/responses/forbidden"
 	tasks := cron.ListTasks()
-	listOpts := utils.GetListOptions(ctx)
-	start, end := listOpts.GetStartEnd()
+	count := len(tasks)
 
-	if len(tasks) > listOpts.PageSize {
-		tasks = tasks[start:end]
-	}
+	listOpts := utils.GetListOptions(ctx)
+	tasks = util.PaginateSlice(tasks, listOpts.Page, listOpts.PageSize).(cron.TaskTable)
 
 	res := make([]structs.Cron, len(tasks))
 	for i, task := range tasks {
@@ -53,6 +53,9 @@ func ListCronTasks(ctx *context.APIContext) {
 			ExecTimes: task.ExecTimes,
 		}
 	}
+
+	ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
+	ctx.Header().Set("Access-Control-Expose-Headers", "X-Total-Count")
 	ctx.JSON(http.StatusOK, res)
 }
 

routers/api/v1/notify/repo.go

@@ -5,6 +5,7 @@
 package notify
 
 import (
+	"fmt"
 	"net/http"
 	"strings"
 	"time"
@@ -108,6 +109,12 @@ func ListRepoNotifications(ctx *context.APIContext) {
 	}
 	opts.RepoID = ctx.Repo.Repository.ID
 
+	totalCount, err := models.CountNotifications(opts)
+	if err != nil {
+		ctx.InternalServerError(err)
+		return
+	}
+
 	nl, err := models.GetNotifications(opts)
 	if err != nil {
 		ctx.InternalServerError(err)
@@ -119,6 +126,8 @@ func ListRepoNotifications(ctx *context.APIContext) {
 		return
 	}
 
+	ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", totalCount))
+	ctx.Header().Set("Access-Control-Expose-Headers", "X-Total-Count")
 	ctx.JSON(http.StatusOK, convert.ToNotifications(nl))
 }
 

routers/api/v1/notify/user.go

@@ -5,6 +5,7 @@
 package notify
 
 import (
+	"fmt"
 	"net/http"
 	"strings"
 	"time"
@@ -69,6 +70,12 @@ func ListNotifications(ctx *context.APIContext) {
 		return
 	}
 
+	totalCount, err := models.CountNotifications(opts)
+	if err != nil {
+		ctx.InternalServerError(err)
+		return
+	}
+
 	nl, err := models.GetNotifications(opts)
 	if err != nil {
 		ctx.InternalServerError(err)
@@ -80,6 +87,8 @@ func ListNotifications(ctx *context.APIContext) {
 		return
 	}
 
+	ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", totalCount))
+	ctx.Header().Set("Access-Control-Expose-Headers", "X-Total-Count")
 	ctx.JSON(http.StatusOK, convert.ToNotifications(nl))
 }
 

routers/api/v1/org/hook.go

@@ -50,6 +50,8 @@ func ListHooks(ctx *context.APIContext) {
 	for i, hook := range orgHooks {
 		hooks[i] = convert.ToHook(org.HomeLink(), hook)
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, hooks)
 }
 

routers/api/v1/org/label.go

@@ -49,6 +49,7 @@ func ListLabels(ctx *context.APIContext) {
 		return
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, convert.ToLabelList(labels))
 }
 

routers/api/v1/org/member.go

@@ -35,6 +35,7 @@ func listMembers(ctx *context.APIContext, publicOnly bool) {
 		apiMembers[i] = convert.ToUser(member, ctx.User)
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, apiMembers)
 }
 

routers/api/v1/org/team.go

@@ -62,6 +62,8 @@ func ListTeams(ctx *context.APIContext) {
 
 		apiTeams[i] = convert.ToTeam(org.Teams[i])
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, apiTeams)
 }
 
@@ -107,6 +109,8 @@ func ListUserTeams(ctx *context.APIContext) {
 		apiTeams[i] = convert.ToTeam(teams[i])
 		apiTeams[i].Organization = apiOrg
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, apiTeams)
 }
 
@@ -339,6 +343,8 @@ func GetTeamMembers(ctx *context.APIContext) {
 	for i, member := range team.Members {
 		members[i] = convert.ToUser(member, ctx.User)
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, members)
 }
 

routers/api/v1/repo/collaborators.go

@@ -56,6 +56,8 @@ func ListCollaborators(ctx *context.APIContext) {
 	for i, collaborator := range collaborators {
 		users[i] = convert.ToUser(collaborator.User, ctx.User)
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, users)
 }
 

routers/api/v1/repo/fork.go

@@ -62,6 +62,8 @@ func ListForks(ctx *context.APIContext) {
 		}
 		apiForks[i] = convert.ToRepo(fork, access)
 	}
+
+	ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", ctx.Repo.Repository.NumForks))
 	ctx.JSON(http.StatusOK, apiForks)
 }
 

routers/api/v1/repo/hook.go

@@ -58,6 +58,8 @@ func ListHooks(ctx *context.APIContext) {
 	for i := range hooks {
 		apiHooks[i] = convert.ToHook(ctx.Repo.RepoLink, hooks[i])
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, &apiHooks)
 }
 

routers/api/v1/repo/issue_comment.go

@@ -89,6 +89,8 @@ func ListIssueComments(ctx *context.APIContext) {
 		comment.Issue = issue
 		apiComments[i] = convert.ToComment(comments[i])
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, &apiComments)
 }
 
@@ -171,6 +173,8 @@ func ListRepoIssueComments(ctx *context.APIContext) {
 	for i := range comments {
 		apiComments[i] = convert.ToComment(comments[i])
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, &apiComments)
 }
 

routers/api/v1/repo/issue_stopwatch.go

@@ -231,5 +231,6 @@ func GetStopwatches(ctx *context.APIContext) {
 		return
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, apiSWs)
 }

routers/api/v1/repo/issue_tracked_time.go

@@ -129,6 +129,8 @@ func ListTrackedTimes(ctx *context.APIContext) {
 		ctx.Error(http.StatusInternalServerError, "LoadAttributes", err)
 		return
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, convert.ToTrackedTimeList(trackedTimes))
 }
 
@@ -540,6 +542,8 @@ func ListTrackedTimesByRepository(ctx *context.APIContext) {
 		ctx.Error(http.StatusInternalServerError, "LoadAttributes", err)
 		return
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, convert.ToTrackedTimeList(trackedTimes))
 }
 
@@ -596,5 +600,6 @@ func ListMyTrackedTimes(ctx *context.APIContext) {
 		return
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, convert.ToTrackedTimeList(trackedTimes))
 }

routers/api/v1/repo/key.go

@@ -104,6 +104,7 @@ func ListDeployKeys(ctx *context.APIContext) {
 		}
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, &apiKeys)
 }
 

routers/api/v1/repo/label.go

@@ -55,6 +55,7 @@ func ListLabels(ctx *context.APIContext) {
 		return
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, convert.ToLabelList(labels))
 }
 

routers/api/v1/repo/milestone.go

@@ -72,6 +72,8 @@ func ListMilestones(ctx *context.APIContext) {
 	for i := range milestones {
 		apiMilestones[i] = convert.ToAPIMilestone(milestones[i])
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, &apiMilestones)
 }
 

routers/api/v1/repo/pull_review.go

@@ -95,6 +95,7 @@ func ListPullReviews(ctx *context.APIContext) {
 		return
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, &apiReviews)
 }
 

routers/api/v1/repo/star.go

@@ -5,6 +5,7 @@
 package repo
 
 import (
+	"fmt"
 	"net/http"
 
 	"code.gitea.io/gitea/modules/context"
@@ -52,5 +53,8 @@ func ListStargazers(ctx *context.APIContext) {
 	for i, stargazer := range stargazers {
 		users[i] = convert.ToUser(stargazer, ctx.User)
 	}
+
+	ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", ctx.Repo.Repository.NumStars))
+	ctx.Header().Set("Access-Control-Expose-Headers", "X-Total-Count")
 	ctx.JSON(http.StatusOK, users)
 }

routers/api/v1/repo/status.go

@@ -267,5 +267,6 @@ func GetCombinedCommitStatusByRef(ctx *context.APIContext) {
 
 	combiStatus := convert.ToCombinedStatus(statuses, convert.ToRepo(repo, ctx.Repo.AccessMode))
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, combiStatus)
 }

routers/api/v1/repo/subscriber.go

@@ -52,5 +52,7 @@ func ListSubscribers(ctx *context.APIContext) {
 	for i, subscriber := range subscribers {
 		users[i] = convert.ToUser(subscriber, ctx.User)
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, users)
 }

routers/api/v1/repo/tag.go

@@ -61,6 +61,7 @@ func ListTags(ctx *context.APIContext) {
 		apiTags[i] = convert.ToTag(ctx.Repo.Repository, tags[i])
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, &apiTags)
 }
 

routers/api/v1/repo/teams.go

@@ -57,6 +57,7 @@ func ListTeams(ctx *context.APIContext) {
 		apiTeams[i] = convert.ToTeam(teams[i])
 	}
 
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, apiTeams)
 }
 

routers/api/v1/repo/topic.go

@@ -61,6 +61,8 @@ func ListTopics(ctx *context.APIContext) {
 	for i, topic := range topics {
 		topicNames[i] = topic.Name
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, map[string]interface{}{
 		"topics": topicNames,
 	})
@@ -292,6 +294,8 @@ func TopicSearch(ctx *context.APIContext) {
 	for i, topic := range topics {
 		topicResponses[i] = convert.ToTopicResponse(topic)
 	}
+
+	// TODO: ctx.Header().Set("X-Total-Count", fmt.Sprintf("%d", count))
 	ctx.JSON(http.StatusOK, map[string]interface{}{
 		"topics": topicResponses,
 	})