[feature] Add partial text search for accounts + statuses (#1836)

1 files changed, 133 insertions, 54 deletions

diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml
index cbd68532f..a0ee30cab 100644
--- a/docs/api/swagger.yaml
+++ b/docs/api/swagger.yaml
@@ -3111,6 +3111,38 @@ paths:
             summary: Delete your account.
             tags:
                 - accounts
+    /api/v1/accounts/lookup:
+        get:
+            operationId: accountLookupGet
+            parameters:
+                - description: The username or Webfinger address to lookup.
+                  in: query
+                  name: acct
+                  required: true
+                  type: string
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: Result of the lookup.
+                    schema:
+                        $ref: '#/definitions/account'
+                "400":
+                    description: bad request
+                "401":
+                    description: unauthorized
+                "404":
+                    description: not found
+                "406":
+                    description: not acceptable
+                "500":
+                    description: internal server error
+            security:
+                - OAuth2 Bearer:
+                    - read:accounts
+            summary: Quickly lookup a username to see if it is available, skipping WebFinger resolution.
+            tags:
+                - accounts
     /api/v1/accounts/relationships:
         get:
             operationId: accountRelationships
@@ -3147,6 +3179,68 @@ paths:
             summary: See your account's relationships with the given account IDs.
             tags:
                 - accounts
+    /api/v1/accounts/search:
+        get:
+            operationId: accountSearchGet
+            parameters:
+                - default: 40
+                  description: Number of results to try to return.
+                  in: query
+                  maximum: 80
+                  minimum: 1
+                  name: limit
+                  type: integer
+                - default: 0
+                  description: Page number of results to return (starts at 0). This parameter is currently not used, offsets over 0 will always return 0 results.
+                  in: query
+                  maximum: 10
+                  minimum: 0
+                  name: offset
+                  type: integer
+                - description: |-
+                    Query string to search for. This can be in the following forms:
+                    - `@[username]` -- search for an account with the given username on any domain. Can return multiple results.
+                    - `@[username]@[domain]` -- search for a remote account with exact username and domain. Will only ever return 1 result at most.
+                    - any arbitrary string -- search for accounts containing the given string in their username or display name. Can return multiple results.
+                  in: query
+                  name: q
+                  required: true
+                  type: string
+                - default: false
+                  description: If query is for `@[username]@[domain]`, or a URL, allow the GoToSocial instance to resolve the search by making calls to remote instances (webfinger, ActivityPub, etc).
+                  in: query
+                  name: resolve
+                  type: boolean
+                - default: false
+                  description: Show only accounts that the requesting account follows. If this is set to `true`, then the GoToSocial instance will enhance the search by also searching within account notes, not just in usernames and display names.
+                  in: query
+                  name: following
+                  type: boolean
+            produces:
+                - application/json
+            responses:
+                "200":
+                    description: Results of the search.
+                    schema:
+                        items:
+                            $ref: '#/definitions/account'
+                        type: array
+                "400":
+                    description: bad request
+                "401":
+                    description: unauthorized
+                "404":
+                    description: not found
+                "406":
+                    description: not acceptable
+                "500":
+                    description: internal server error
+            security:
+                - OAuth2 Bearer:
+                    - read:accounts
+            summary: Search for accounts by username and/or display name.
+            tags:
+                - accounts
     /api/v1/accounts/update_credentials:
         patch:
             consumes:
@@ -5278,81 +5372,66 @@ paths:
             description: If statuses are in the result, they will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer).
             operationId: searchGet
             parameters:
-                - description: If type is `statuses`, then statuses returned will be authored only by this account.
-                  in: query
-                  name: account_id
-                  type: string
-                  x-go-name: AccountID
-                - description: |-
-                    Return results *older* than this id.
-
-                    The entry with this ID will not be included in the search results.
+                - description: Return only items *OLDER* than the given max ID. The item with the specified ID will not be included in the response. Currently only used if 'type' is set to a specific type.
                   in: query
                   name: max_id
                   type: string
-                  x-go-name: MaxID
-                - description: |-
-                    Return results *newer* than this id.
-
-                    The entry with this ID will not be included in the search results.
+                - description: Return only items *immediately newer* than the given min ID. The item with the specified ID will not be included in the response. Currently only used if 'type' is set to a specific type.
                   in: query
                   name: min_id
                   type: string
-                  x-go-name: MinID
-                - description: |-
-                    Type of the search query to perform.
-
-                    Must be one of: `accounts`, `hashtags`, `statuses`.
+                - default: 20
+                  description: Number of each type of item to return.
                   in: query
-                  name: type
-                  required: true
-                  type: string
-                  x-go-name: Type
-                - default: false
-                  description: Filter out tags that haven't been reviewed and approved by an instance admin.
+                  maximum: 40
+                  minimum: 1
+                  name: limit
+                  type: integer
+                - default: 0
+                  description: Page number of results to return (starts at 0). This parameter is currently not used, page by selecting a specific query type and using maxID and minID instead.
                   in: query
-                  name: exclude_unreviewed
-                  type: boolean
-                  x-go-name: ExcludeUnreviewed
+                  maximum: 10
+                  minimum: 0
+                  name: offset
+                  type: integer
                 - description: |-
-                    String to use as a search query.
-
-                    For accounts, this should be in the format `@someaccount@some.instance.com`, or the format `https://some.instance.com/@someaccount`
-
-                    For a status, this can be in the format: `https://some.instance.com/@someaccount/SOME_ID_OF_A_STATUS`
+                    Query string to search for. This can be in the following forms:
+                    - `@[username]` -- search for an account with the given username on any domain. Can return multiple results.
+                    - @[username]@[domain]` -- search for a remote account with exact username and domain. Will only ever return 1 result at most.
+                    - `https://example.org/some/arbitrary/url` -- search for an account OR a status with the given URL. Will only ever return 1 result at most.
+                    - any arbitrary string -- search for accounts or statuses containing the given string. Can return multiple results.
                   in: query
                   name: q
                   required: true
                   type: string
-                  x-go-name: Query
+                - description: |-
+                    Type of item to return. One of:
+                    - `` -- empty string; return any/all results.
+                    - `accounts` -- return account(s).
+                    - `statuses` -- return status(es).
+                    - `hashtags` -- return hashtag(s).
+                    If `type` is specified, paging can be performed using max_id and min_id parameters.
+                    If `type` is not specified, see the `offset` parameter for paging.
+                  in: query
+                  name: type
+                  type: string
                 - default: false
-                  description: Attempt to resolve the query by performing a remote webfinger lookup, if the query includes a remote host.
+                  description: If searching query is for `@[username]@[domain]`, or a URL, allow the GoToSocial instance to resolve the search by making calls to remote instances (webfinger, ActivityPub, etc).
                   in: query
                   name: resolve
                   type: boolean
-                  x-go-name: Resolve
-                - default: 20
-                  description: Maximum number of results to load, per type.
-                  format: int64
-                  in: query
-                  maximum: 40
-                  minimum: 1
-                  name: limit
-                  type: integer
-                  x-go-name: Limit
-                - default: 0
-                  description: Offset for paginating search results.
-                  format: int64
-                  in: query
-                  name: offset
-                  type: integer
-                  x-go-name: Offset
                 - default: false
-                  description: Only include accounts that the searching account is following.
+                  description: If search type includes accounts, and search query is an arbitrary string, show only accounts that the requesting account follows. If this is set to `true`, then the GoToSocial instance will enhance the search by also searching within account notes, not just in usernames and display names.
                   in: query
                   name: following
                   type: boolean
-                  x-go-name: Following
+                - default: false
+                  description: If searching for hashtags, exclude those not yet approved by instance admin. Currently this parameter is unused.
+                  in: query
+                  name: exclude_unreviewed
+                  type: boolean
+            produces:
+                - application/json
             responses:
                 "200":
                     description: Results of the search.