add:

- multiple pagination methods
- "include" parameter in /search route :
-- facets : facets are no more returned by default
-- results.stories.children : to populate the children of stories
- "story_children_limit" parameter in /search route
  will limit the number of children populated by story
- "count" (for results) and "children_count" (for stories in results) is the number of items in the current page
- "total" (for results) and "children_total" (for stories in results) is the total number of items

todo: swagger doc (but impossible to describe related/excluded parameters (like pagination methods in /search)

API_documentation/v3/api.yaml

@@ -32,6 +32,27 @@ components:
             flows:
                 password:   # <-- OAuth flow(authorizationCode, implicit, password or clientCredentials)
                     tokenUrl: azea
+    parameters:
+        offsetParam:
+            name: offset
+            in: query
+            description: offset in records count
+            required: false
+            schema:
+                type: integer
+                minimum: 0
+                default: 0
+        limitParam:
+            name: limit
+            in: query
+            description: number of results
+            required: false
+            schema:
+                type: integer
+                minimum: 1
+                maximum: 100
+                default: 10
+
 paths:
     '/me':
         get:
@@ -44,6 +65,96 @@ paths:
                 default:
                     description: Any error
 
+# ---------------- search ----------------
+    '/search':
+        post:
+            tags:
+                - search
+            description: 'Fulltext search for records or stories.
+                pagination: use (offset/limit) OR (page/per_page)'
+            parameters:
+                - name: query
+                  in: query
+                  description: 'The fulltext query (<empty> = search all)'
+                  required: false
+                  schema:
+                      type: string
+                      example: 'dogs OR cats'
+                      default: ''
+                - name: search_type
+                  in: query
+                  description: 0 to search for records ; 1 to search for stories
+                  required: false
+                  schema:
+                      type: integer
+                      minimum: 0
+                      maximum: 1
+                      default: 0
+                - name: offset
+                  in: query
+                  description: offset in records count, from 0. Use along with "limit"
+                  required: false
+                  schema:
+                      type: integer
+                      minimum: 0
+                      default: 0
+                - name: limit
+                  in: query
+                  description: number of results. Use along with "offset"
+                  required: false
+                  schema:
+                      type: integer
+                      minimum: 1
+                      maximum: 100
+                      default: 10
+                - name: page
+                  in: query
+                  description: page number, from 1. Use along with "per_page"
+                  required: false
+                  schema:
+                      type: integer
+                      minimum: 1
+                      default: 1
+                - name: per_page
+                  in: query
+                  description: number of results per page. Use along with "page"
+                  required: false
+                  schema:
+                      type: integer
+                      minimum: 1
+                      maximum: 100
+                      default: 10
+                - name: story_children_limit
+                  in: query
+                  description: For stories, include N children
+                  required: false
+                  schema:
+                      type: integer
+                      minimum: 0
+                      maximum: 10
+                      default: 0
+                - name: include
+                  in: query
+                  description: Elements to be included in response
+                  required: false
+                  schema:
+
+                      anyOf:
+                          - enum:
+                                - facets
+                                - result.stories.children
+                  explode: true
+            responses:
+                200:
+                    description: ok
+                    content:
+                        application/json:
+                            schema:
+                                $ref: 'schemas.yaml#/ApiResponse_search'
+                default:
+                    $ref: 'responses.yaml#/error_response'
+
+# ------------ record -----------
     '/records/{base_id}':
         post:
             tags:

API_documentation/v3/schemas.yaml

@@ -63,6 +63,43 @@ ApiResponse_record:
             $ref: '#/ApiResponse_meta'
         response:
             $ref: '#/Record'
+
+# -------------------- search ---------------
+ApiResponse_search:
+    type: object
+    properties:
+        meta:
+            $ref: '#/ApiResponse_meta'
+        response:
+            $ref: '#/ApiResponse_search_response'
+ApiResponse_search_response:
+    type: object
+    properties:
+        offset:
+            type: integer
+            description: 'The pagination offset as passed in request'
+        limit:
+            type: integer
+            description: 'The pagination limit as passed in request'
+        page_result_count:
+            type: integer
+            description: 'The number of results in this page [0...limit]'
+        total_result_count:
+            type: integer
+            description: 'The total number of results request'
+        results:
+            type: object
+            properties:
+                stories:
+                    type: array
+                    items:
+                        $ref: '#/Record'
+                records:
+                    type: array
+                    items:
+                        $ref: '#/Record'
+
+
 ID:
     type: integer
 Permalink: