Changeset View
Changeset View
Standalone 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}. |