Ensure pagination order is deterministic

jpahm · jpahm · commit c193422f06f7 · 2025-03-24T17:37:32.000-05:00
diff --git a/api/controllers/course.go b/api/controllers/course.go
@@ -139,8 +139,10 @@ func CourseAll(c *gin.Context) {
 
 // @Id courseSectionSearch
 // @Router /course/sections [get]
-// @Description "Returns all the sections of all the courses matching the query's string-typed key-value pairs"
+// @Description "Returns paginated list of sections of all the courses matching the query's string-typed key-value pairs. See former_offset and latter_offset for pagination details."
 // @Produce json
+// @Param former_offset query number false "The starting position of the current page of courses (e.g. For starting at the 17th course, former_offset=16)."
+// @Param latter_offset query number false "The starting position of the current page of sections (e.g. For starting at the 4th section, latter_offset=3)."
 // @Param course_number query string false "The course's official number"
 // @Param subject_prefix query string false "The course's subject prefix"
 // @Param title query string false "The course's title"
@@ -243,6 +245,9 @@ func courseSection(flag string, c *gin.Context) {
 		// replace the courses with sections
 		bson.D{{Key: "$replaceWith", Value: "$sections"}},
 
+		// keep order deterministic between calls
+		bson.D{{Key: "$sort", Value: bson.D{{Key: "_id", Value: 1}}}},
+
 		// paginate the sections
 		bson.D{{Key: "$skip", Value: paginateMap["latter_offset"]}},
 		bson.D{{Key: "$limit", Value: paginateMap["limit"]}},
diff --git a/api/controllers/professor.go b/api/controllers/professor.go
@@ -148,8 +148,10 @@ func ProfessorAll(c *gin.Context) {
 
 // @Id professorCourseSearch
 // @Router /professor/courses [get]
-// @Description "Returns all of the courses of all the professors matching the query's string-typed key-value pairs"
+// @Description "Returns paginated list of the courses of all the professors matching the query's string-typed key-value pairs. See former_offset and latter_offset for pagination details."
 // @Produce json
+// @Param former_offset query number false "The starting position of the current page of professors (e.g. For starting at the 17th professor, former_offset=16)."
+// @Param latter_offset query number false "The starting position of the current page of courses (e.g. For starting at the 4th course, latter_offset=3)."
 // @Param first_name query string false "The professor's first name"
 // @Param last_name query string false "The professor's last name"
 // @Param titles query string false "One of the professor's title"
@@ -252,6 +254,9 @@ func professorCourse(flag string, c *gin.Context) {
 		// replace the combination of ids and courses with the courses entirely
 		bson.D{{Key: "$replaceWith", Value: "$courses"}},
 
+		// keep order deterministic between calls
+		bson.D{{Key: "$sort", Value: bson.D{{Key: "_id", Value: 1}}}},
+
 		// paginate the courses
 		bson.D{{Key: "$skip", Value: paginateMap["latter_offset"]}},
 		bson.D{{Key: "$limit", Value: paginateMap["limit"]}},
@@ -275,8 +280,10 @@ func professorCourse(flag string, c *gin.Context) {
 
 // @Id professorSectionSearch
 // @Router /professor/sections [get]
-// @Description "Returns all of the sections of all the professors matching the query's string-typed key-value pairs"
+// @Description "Returns paginated list of the sections of all the professors matching the query's string-typed key-value pairs. See former_offset and latter_offset for pagination details."
 // @Produce json
+// @Param former_offset query number false "The starting position of the current page of professors (e.g. For starting at the 17th professor, former_offset=16)."
+// @Param latter_offset query number false "The starting position of the current page of sections (e.g. For starting at the 4th section, latter_offset=3)."
 // @Param first_name query string false "The professor's first name"
 // @Param last_name query string false "The professor's last name"
 // @Param titles query string false "One of the professor's title"
@@ -368,6 +375,9 @@ func professorSection(flag string, c *gin.Context) {
 		// replace the combination of ids and sections with the sections entirely
 		bson.D{{Key: "$replaceWith", Value: "$sections"}},
 
+		// keep order deterministic between calls
+		bson.D{{Key: "$sort", Value: bson.D{{Key: "_id", Value: 1}}}},
+
 		// paginate the sections
 		bson.D{{Key: "$skip", Value: paginateMap["latter_offset"]}},
 		bson.D{{Key: "$limit", Value: paginateMap["limit"]}},
diff --git a/api/docs/docs.go b/api/docs/docs.go
@@ -166,12 +166,24 @@ const docTemplate = `{
         },
         "/course/sections": {
             "get": {
-                "description": "\"Returns all the sections of all the courses matching the query's string-typed key-value pairs\"",
+                "description": "\"Returns paginated list of sections of all the courses matching the query's string-typed key-value pairs. See former_offset and latter_offset for pagination details.\"",
                 "produces": [
                     "application/json"
                 ],
                 "operationId": "courseSectionSearch",
                 "parameters": [
+                    {
+                        "type": "number",
+                        "description": "The starting position of the current page of courses (e.g. For starting at the 17th course, former_offset=16).",
+                        "name": "former_offset",
+                        "in": "query"
+                    },
+                    {
+                        "type": "number",
+                        "description": "The starting position of the current page of sections (e.g. For starting at the 4th section, latter_offset=3).",
+                        "name": "latter_offset",
+                        "in": "query"
+                    },
                     {
                         "type": "string",
                         "description": "The course's official number",
@@ -684,12 +696,24 @@ const docTemplate = `{
         },
         "/professor/courses": {
             "get": {
-                "description": "\"Returns all of the courses of all the professors matching the query's string-typed key-value pairs\"",
+                "description": "\"Returns paginated list of the courses of all the professors matching the query's string-typed key-value pairs. See former_offset and latter_offset for pagination details.\"",
                 "produces": [
                     "application/json"
                 ],
                 "operationId": "professorCourseSearch",
                 "parameters": [
+                    {
+                        "type": "number",
+                        "description": "The starting position of the current page of professors (e.g. For starting at the 17th professor, former_offset=16).",
+                        "name": "former_offset",
+                        "in": "query"
+                    },
+                    {
+                        "type": "number",
+                        "description": "The starting position of the current page of courses (e.g. For starting at the 4th course, latter_offset=3).",
+                        "name": "latter_offset",
+                        "in": "query"
+                    },
                     {
                         "type": "string",
                         "description": "The professor's first name",
@@ -826,12 +850,24 @@ const docTemplate = `{
         },
         "/professor/sections": {
             "get": {
-                "description": "\"Returns all of the sections of all the professors matching the query's string-typed key-value pairs\"",
+                "description": "\"Returns paginated list of the sections of all the professors matching the query's string-typed key-value pairs. See former_offset and latter_offset for pagination details.\"",
                 "produces": [
                     "application/json"
                 ],
                 "operationId": "professorSectionSearch",
                 "parameters": [
+                    {
+                        "type": "number",
+                        "description": "The starting position of the current page of professors (e.g. For starting at the 17th professor, former_offset=16).",
+                        "name": "former_offset",
+                        "in": "query"
+                    },
+                    {
+                        "type": "number",
+                        "description": "The starting position of the current page of sections (e.g. For starting at the 4th section, latter_offset=3).",
+                        "name": "latter_offset",
+                        "in": "query"
+                    },
                     {
                         "type": "string",
                         "description": "The professor's first name",
diff --git a/api/docs/swagger.yaml b/api/docs/swagger.yaml
@@ -495,10 +495,21 @@ paths:
             type: array
   /course/sections:
     get:
-      description: '"Returns all the sections of all the courses matching the query''s
-        string-typed key-value pairs"'
+      description: '"Returns paginated list of sections of all the courses matching
+        the query''s string-typed key-value pairs. See former_offset and latter_offset
+        for pagination details."'
       operationId: courseSectionSearch
       parameters:
+      - description: The starting position of the current page of courses (e.g. For
+          starting at the 17th course, former_offset=16).
+        in: query
+        name: former_offset
+        type: number
+      - description: The starting position of the current page of sections (e.g. For
+          starting at the 4th section, latter_offset=3).
+        in: query
+        name: latter_offset
+        type: number
       - description: The course's official number
         in: query
         name: course_number
@@ -866,10 +877,21 @@ paths:
             type: array
   /professor/courses:
     get:
-      description: '"Returns all of the courses of all the professors matching the
-        query''s string-typed key-value pairs"'
+      description: '"Returns paginated list of the courses of all the professors matching
+        the query''s string-typed key-value pairs. See former_offset and latter_offset
+        for pagination details."'
       operationId: professorCourseSearch
       parameters:
+      - description: The starting position of the current page of professors (e.g.
+          For starting at the 17th professor, former_offset=16).
+        in: query
+        name: former_offset
+        type: number
+      - description: The starting position of the current page of courses (e.g. For
+          starting at the 4th course, latter_offset=3).
+        in: query
+        name: latter_offset
+        type: number
       - description: The professor's first name
         in: query
         name: first_name
@@ -964,10 +986,21 @@ paths:
             type: array
   /professor/sections:
     get:
-      description: '"Returns all of the sections of all the professors matching the
-        query''s string-typed key-value pairs"'
+      description: '"Returns paginated list of the sections of all the professors
+        matching the query''s string-typed key-value pairs. See former_offset and
+        latter_offset for pagination details."'
       operationId: professorSectionSearch
       parameters:
+      - description: The starting position of the current page of professors (e.g.
+          For starting at the 17th professor, former_offset=16).
+        in: query
+        name: former_offset
+        type: number
+      - description: The starting position of the current page of sections (e.g. For
+          starting at the 4th section, latter_offset=3).
+        in: query
+        name: latter_offset
+        type: number
       - description: The professor's first name
         in: query
         name: first_name
