Differential D14798 Diff 35779 src/docs/user/userguide/conduit_search.diviner

Changeset View

Standalone View

src/docs/user/userguide/conduit_search.diviner

This file was added.

				@title Conduit API: Using Search Endpoints
				@group conduit

				Describes how to use search endpoints to find objects and read information.

				Overview
				========

				Many applications provide `search` endpoints, which are the primary way to
				get information about objects (like tasks) using the API.

				To read information about objects, you'll specify a //query// which describes
				which objects you want to retrieve. You can query for specific objects by
				ID, or for a list of objects satisfying certain constraints (for example, open
				tasks in a particular project).

				The best reference for a particular `search` endpoint is the Conduit API
				console. For example, you can find the console page for `maniphest.search` by
				navigating to {nav Conduit > maniphest.search} in the web UI. This page
				contains detailed information about the endpoint and how it can be used.


				Specifying a Query
				==================

				The simplest query you can use is no query at all: just make a request with
				no parameters. This will return the first page of visible objects. Most
				applications sort objects by creation date by default, so usually this is
				the 100 most recent objects.

				The easiest way to constrain results is to use a builtin query or a custom
				query that you build using the web UI. To do this, first issue the query in
				the web UI (for example, by clicking the builtin link on the left nav of the
				list view, or by submitting the query form).

				The results page will include a //query key// in the URL. For builtin queries,
				this is usually a human-readable term like `all` or `active`. For custom
				queries, it is a hash value which looks something like `MT0Rh0fB2x4I`.

				You can submit this key in the `queryKey` parameter to issue the exact same
				query via the Conduit API. This provides a simple way to build complex queries:
				just build the via the web UI, then reuse the same query in the API.

				If you need more control or want to build dynamic queries, use the
				`constraints` parameter to set constraints for individual query fields.

				For more details, consult the Conduit API console documentation for the
				method you're using. It includes documentation on all available constraints
				and lists builtin and saved query keys.


				Attachments
				===========

				By default, queries return basic information about objects. If you want more
				detailed information, most applications offer //attachments// which can let
				you retrieve more information.

				For example, subscribers and projects are not returned by default, but you
				can use subscribers to query them if you need this data.

				Asking for more data means a slower query and a larger result, so usually you
				should only ask for data you need.

				The Conduit API console page for each query method has detailed information
				on which attachments it supports.


				Next Steps
				==========

				Continue by:

				- returning to the @{article:Conduit API Overview}.