Make all REST categories have subcategories (#38559)
Co-authored-by: Rachael Sewell <rachmari@github.com>
This commit is contained in:
Sarah Edwards
18
content/rest/search/index.md
Normal file
18
content/rest/search/index.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: Search
|
||||
intro: >-
|
||||
Use the REST API to search for specific items on {% data
|
||||
variables.product.product_name %}.
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
topics:
|
||||
- API
|
||||
children:
|
||||
- /search
|
||||
autogenerated: rest
|
||||
---
|
||||
|
||||
<!-- Content after this section is automatically generated -->
|
||||
186
content/rest/search/search.md
Normal file
186
content/rest/search/search.md
Normal file
@@ -0,0 +1,186 @@
|
||||
---
|
||||
title: Search
|
||||
intro: >-
|
||||
Use the REST API to search for specific items on {% data
|
||||
variables.product.product_name %}.
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
topics:
|
||||
- API
|
||||
redirect_from:
|
||||
- /rest/reference/search
|
||||
autogenerated: rest
|
||||
---
|
||||
|
||||
## About search
|
||||
|
||||
You can use the REST API to search for the specific item you want to find. For example, you can find a user or a specific file in a repository. Think of it the way you think of performing a search on Google. It's designed to help you find the one result you're looking for (or maybe the few results you're looking for). Just like searching on Google, you sometimes want to see a few pages of search results so that you can find the item that best meets your needs. To satisfy that need, the {% data variables.product.product_name %} REST API provides **up to 1,000 results for each search**.
|
||||
|
||||
You can narrow your search using queries. To learn more about the search query syntax, see "[AUTOTITLE](/rest/search#constructing-a-search-query)."
|
||||
|
||||
### Ranking search results
|
||||
|
||||
Unless another sort option is provided as a query parameter, results are sorted by best match in descending order. Multiple factors are combined to boost the most relevant item to the top of the result list.
|
||||
|
||||
### Rate limit
|
||||
|
||||
{% data reusables.enterprise.rate_limit %}
|
||||
|
||||
The REST API has a custom rate limit for searching. For authenticated requests, you can make up to
|
||||
30 requests per minute{% ifversion fpt or ghec %} for all search endpoints except for the "[Search code](/rest/search#search-code)" endpoint. The "[Search code](/rest/search#search-code)" endpoint requires you to authenticate and limits you to 10 requests per minute{% endif %}. For unauthenticated requests, the rate limit allows you to make up to 10 requests per minute.
|
||||
|
||||
See the [rate limit documentation](/rest/rate-limit) for details on
|
||||
determining your current rate limit status.
|
||||
|
||||
### Constructing a search query
|
||||
|
||||
Each endpoint for searching uses [query parameters](https://en.wikipedia.org/wiki/Query_string) to perform searches on {% data variables.product.product_name %}. See the individual endpoints for examples that include the endpoint and query parameters.
|
||||
|
||||
A query can contain any combination of search qualifiers supported on {% data variables.product.product_name %}. The format of the search query is:
|
||||
|
||||
```
|
||||
SEARCH_KEYWORD_1 SEARCH_KEYWORD_N QUALIFIER_1 QUALIFIER_N
|
||||
```
|
||||
|
||||
For example, if you wanted to search for all _repositories_ owned by `defunkt` that
|
||||
contained the word `GitHub` and `Octocat` in the README file, you would use the
|
||||
following query with the _search repositories_ endpoint:
|
||||
|
||||
```
|
||||
GitHub Octocat in:readme user:defunkt
|
||||
```
|
||||
|
||||
**Note:** Be sure to use your language's preferred HTML-encoder to construct your query strings. For example:
|
||||
|
||||
```javascript
|
||||
// JavaScript
|
||||
const queryString = 'q=' + encodeURIComponent('GitHub Octocat in:readme user:defunkt');
|
||||
```
|
||||
|
||||
See "[AUTOTITLE](/search-github/searching-on-github)"
|
||||
for a complete list of available qualifiers, their format, and an example of
|
||||
how to use them. For information about how to use operators to match specific
|
||||
quantities, dates, or to exclude results, see "[AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax)."
|
||||
|
||||
### Limitations on query length
|
||||
|
||||
You cannot use queries that:
|
||||
- are longer than 256 characters (not including operators or qualifiers).
|
||||
- have more than five `AND`, `OR`, or `NOT` operators.
|
||||
|
||||
These search queries will return a "Validation failed" error message.
|
||||
|
||||
### Search scope limits
|
||||
|
||||
To keep the REST API fast for everyone, we limit the number of repositories a query will search through. The REST API will find up to 4,000 repositories that match your filters and return results from those repositories.
|
||||
|
||||
### Timeouts and incomplete results
|
||||
|
||||
To keep the REST API fast for everyone, we limit how long any individual query
|
||||
can run. For queries that [exceed the time limit](https://developer.github.com/changes/2014-04-07-understanding-search-results-and-potential-timeouts/),
|
||||
the API returns the matches that were already found prior to the timeout, and
|
||||
the response has the `incomplete_results` property set to `true`.
|
||||
|
||||
Reaching a timeout does not necessarily mean that search results are incomplete.
|
||||
More results might have been found, but also might not.
|
||||
|
||||
### Access errors or missing search results
|
||||
|
||||
You need to successfully authenticate and have access to the repositories in your search queries, otherwise, you'll see a `422 Unprocessable Entry` error with a "Validation Failed" message. For example, your search will fail if your query includes `repo:`, `user:`, or `org:` qualifiers that request resources that you don't have access to when you sign in on {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
When your search query requests multiple resources, the response will only contain the resources that you have access to and will **not** provide an error message listing the resources that were not returned.
|
||||
|
||||
For example, if your search query searches for the `octocat/test` and `codertocat/test` repositories, but you only have access to `octocat/test`, your response will show search results for `octocat/test` and nothing for `codertocat/test`. This behavior mimics how search works on {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
### Text match metadata
|
||||
|
||||
On {% data variables.product.prodname_dotcom %}, you can use the context provided by code snippets and highlights in search results. The endpoints for searching return additional metadata that allows you to highlight the matching search terms when displaying search results.
|
||||
|
||||
Requests can opt to receive those text fragments in the response, and every fragment is accompanied by numeric offsets identifying the exact location of each matching search term.
|
||||
|
||||
To get this metadata in your search results, specify the `text-match` media type in your `Accept` header.
|
||||
|
||||
```shell
|
||||
application/vnd.github.text-match+json
|
||||
```
|
||||
|
||||
When you provide the `text-match` media type, you will receive an extra key in the JSON payload called `text_matches` that provides information about the position of your search terms within the text and the `property` that includes the search term. Inside the `text_matches` array, each object includes
|
||||
the following attributes:
|
||||
|
||||
Name | Description
|
||||
-----|-----------|
|
||||
`object_url` | The URL for the resource that contains a string property matching one of the search terms.
|
||||
`object_type` | The name for the type of resource that exists at the given `object_url`.
|
||||
`property` | The name of a property of the resource that exists at `object_url`. That property is a string that matches one of the search terms. (In the JSON returned from `object_url`, the full content for the `fragment` will be found in the property with this name.)
|
||||
`fragment` | A subset of the value of `property`. This is the text fragment that matches one or more of the search terms.
|
||||
`matches` | An array of one or more search terms that are present in `fragment`. The indices (i.e., "offsets") are relative to the fragment. (They are not relative to the _full_ content of `property`.)
|
||||
|
||||
#### Example
|
||||
|
||||
Using a `curl` command, and the [example issue search](#search-issues-and-pull-requests) above, our API
|
||||
request would look like this:
|
||||
|
||||
``` shell
|
||||
curl -H 'Accept: application/vnd.github.text-match+json' \
|
||||
'{% data variables.product.api_url_pre %}/search/issues?q=windows+label:bug \
|
||||
+language:python+state:open&sort=created&order=asc'
|
||||
```
|
||||
|
||||
The response will include a `text_matches` array for each search result. In the JSON below, we have two objects in the `text_matches` array.
|
||||
|
||||
The first text match occurred in the `body` property of the issue. We see a fragment of text from the issue body. The search term (`windows`) appears twice within that fragment, and we have the indices for each occurrence.
|
||||
|
||||
The second text match occurred in the `body` property of one of the issue's comments. We have the URL for the issue comment. And of course, we see a fragment of text from the comment body. The search term (`windows`) appears once within that fragment.
|
||||
|
||||
```json
|
||||
{
|
||||
"text_matches": [
|
||||
{
|
||||
"object_url": "https://api.github.com/repositories/215335/issues/132",
|
||||
"object_type": "Issue",
|
||||
"property": "body",
|
||||
"fragment": "comprehensive windows font I know of).\n\nIf we can find a commonly
|
||||
distributed windows font that supports them then no problem (we can use html
|
||||
font tags) but otherwise the '(21)' style is probably better.\n",
|
||||
"matches": [
|
||||
{
|
||||
"text": "windows",
|
||||
"indices": [
|
||||
14,
|
||||
21
|
||||
]
|
||||
},
|
||||
{
|
||||
"text": "windows",
|
||||
"indices": [
|
||||
78,
|
||||
85
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"object_url": "https://api.github.com/repositories/215335/issues/comments/25688",
|
||||
"object_type": "IssueComment",
|
||||
"property": "body",
|
||||
"fragment": " right after that are a bit broken IMHO :). I suppose we could
|
||||
have some hack that maxes out at whatever the font does...\n\nI'll check
|
||||
what the state of play is on Windows.\n",
|
||||
"matches": [
|
||||
{
|
||||
"text": "Windows",
|
||||
"indices": [
|
||||
163,
|
||||
170
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<!-- Content after this section is automatically generated -->
|
||||
Reference in New Issue
Block a user