ActivityPub Autocomplete Search API Endpoint

Introduction

Social software clients often include a text composition interface. When the user wants to mention another actor, they can type a few letters of the actor's name (or other properties), and get a popup selection of matching actors.

Some social software clients also use typeahead dropdown elements to choose actors in other contexts besides tagging.

Actor autocomplete search is useful in situations when:

The pool of applicable actors is too large to show directly in a list.
Typing the full name or identifier for the actor is tiresome or errorprone.

User stories

This specification is for the following user stories:

Discovery

An [[[ActivityPub]]] API client operating on behalf of an actor can use the actor object to discover the autocomplete search endpoint. The endpoints property of the actor includes properties for useful API endpoints. The actorAutocomplete property defines a [[[RFC6570]]] for an endpoint with the behaviour defined below in Endpoint. The URI template takes a single argument, q, the text typed so far.

This is a minimal example of an actor with an actorAutocomplete endpoint.

        {
          "@context": [
            "https://www.w3.org/ns/activitystreams",
            "https://swicg.github.io/activitypub-api/autocomplete"
          ],
          "id": "https://social.example/user/apuser1",
          "type": "Person",
          "to": "as:Public",
          "preferredUsername": "apuser1",
          "name": "ActivitPub Userone",
          "inbox": "https://social.example/user/apuser1/inbox",
          "outbox": "https://social.example/user/apuser1/outbox",
          "endpoints": {
            "actorAutocomplete": "https://social.example/search/actor/typeahead?search={q}"
          }
        }

Endpoint

The endpoint URI template takes a single parameter, q, representing the text typed so far. The endpoint SHOULD require authentication and SHOULD support bearer tokens as in [[RFC6750]].

This is a minimal example of an HTTP request for the actor autocomplete endpoint. The client has filled in the q parameter with the string "ala". The OAuth bearer token is provided.

        GET /search/actor/typeahead?search=ala HTTP/1.1
        Host: social.example
        Accept: application/activity+json, application/ld+json, application/json
        Authorization: Bearer CJz4LwUWgn1Xfgs4TB307

The endpoint should return an [[[activitystreams-core]]] Collection of actor objects that match the search parameter. The collection may use collection paging.

Example output from the actor autocomplete search endpoint.

        {
          "@context": "https://www.w3.org/ns/activitystreams",
          "type": "Collection",
          "id": "https://social.example/search/actor/typeahead?search=ala",
          "totalItems": 3,
          "items": [
              {
                  "id": "https://other.example/user/C6CEFD42-2109-4719-9E71-231804076FB7",
                  "type": "Person",
                  "name": "Alana Cooper",
                  "preferredUsername": "coopera"
              },
              {
                  "id": "https://third.example/actor/DJQ7R4Xw7mX8GWnueYPpL",
                  "type": "Organization",
                  "name": "Aaling Fisheries",
                  "preferredUsername": "aalingvis1"
              },
              {
                  "id": "https://fanclub.example/group/thelittlepills",
                  "type": "Group",
                  "name": "Alanis Morisette Fan Club",
                  "preferredUsername": "thelittlepills"
              }
          ]
      }

The pool of actors searched is server-defined. The actors found can come from the actor's followers or following collections, from the local server user directory, from a global user directory, or any other source.

The matching algorithm is server-defined. The match can be on different properties of the actor, such as preferredUsername or name, or on other properties. The match can be exact, or by prefix, or fuzzy matching, or another matching algorithm.

The sorting order is descending by relevance as defined by the server for autocompletion. The first items in the collection are the most relevant to the user's needs; later items are less relevant. The actor relevance value is not represented by a property in the results.

All objects returned in the search results MUST be ActivityPub actor objects, with the required properties of ActivityPub actors.

If there are no actors found that match the query parameter, the response MUST still be returned, with an empty Collection. The HTTP status code MUST be 200.

Example output from the actor autocomplete search endpoint with no matching actors.

        {
          "@context": "https://www.w3.org/ns/activitystreams",
          "type": "Collection",
          "id": "https://social.example/search/actor/typeahead?search=xyyngzl",
          "totalItems": 0
        }

Errors

In case of an error, when the endpoint cannot fulfill the request, it MUST return an [[[RFC7807]]] result.

An example error result, when the client has not provided authentication credentials.

        HTTP/1.1 401 Unauthorized
        Content-Type: application/problem+json
        Content-Language: en

        {
          "type": "about:blank",
          "status": "401",
          "title": "Unauthorized",
          "detail": "This endpoint requires an OAuth 2.0 bearer token"
        }

This specification defines a custom problem detail type for a specific error situation. Many typeahead search systems require a minimum number of characters in the query parameter to execute a search, to prevent overly broad results. This error type is used if the minimum number of characters is not provided.

An error result indicating the minimum number of characters was not met.

        HTTP/1.1 400 Bad Request
        Content-Type: application/problem+json

        {
            "type": "https://swicg.github.io/activitypub-api/autocomplete#minimumChars",
            "title": "Search param too small",
            "detail": "The q parameter must be 4 characters or more",
            "q": "al",
            "minimum": 4
        }

Terms

The context URI for terms defined in this document is https://swicg.github.io/activitypub-api/autocomplete. The namespace for the terms is https://swicg.github.io/activitypub-api/autocomplete#.

The following extension term is defined in this document.

actorAutocomplete

URI:	`https://swicg.github.io/activitypub-api/autocomplete#actorAutocomplete` `autocomplete:actorAutocomplete` `actorAutocomplete`
Notes:	Defines an endpoint for autocomplete search for actors. Discoverable as defined in Discovery. An endpoint so described must behave as in Endpoint.
Domain:	`Object` (an ActivityPub Actor `endpoints` object)
Range:	`xsd:anyURI`
Functional:	`true`