Skip to content

Commit 31361ee

Browse files
Lagojagcurtis
Lagoja
and
gcurtis
authored
Initial Nixhub docs (#2186)
## Summary Docs for proposed Nixhub API ## How was it tested? Localhost --------- Signed-off-by: John Lago <[email protected]> Co-authored-by: Greg Curtis <[email protected]>
1 parent 48884c0 commit 31361ee

File tree

11 files changed

+35351
-13253
lines changed

11 files changed

+35351
-13253
lines changed

‎docs/app/docs/nixhub/get-a-package.api.mdx‎

Lines changed: 492 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/app/docs/nixhub/index.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: "Nixhub API"
3+
description: "API for searching and resolving package dependencies"
4+
sidebar_label: Introduction
5+
sidebar_position: 0
6+
hide_title: true
7+
custom_edit_url: null
8+
---
9+
10+
import ApiLogo from "@theme/ApiLogo";
11+
import Heading from "@theme/Heading";
12+
import SchemaTabs from "@theme/SchemaTabs";
13+
import TabItem from "@theme/TabItem";
14+
import Export from "@theme/ApiExplorer/Export";
15+
import DocCardList from "@theme/DocCardList";
16+
17+
<span
18+
className={"theme-doc-version-badge badge badge--secondary"}
19+
children={"Version: 2.0.0"}
20+
>
21+
</span>
22+
23+
# Using the Nixhub API
24+
25+
The Nixhub API lets you search over 1 million package versions for over 100,000 Nix packages. You can use the Nixhub API to search for packages, resolve historic versions, and then install them using Devbox or Nix. Nixhub is designed to be simple and easy to use, and is free to use for personal use.
26+
27+
Nixhub is a RESTful API that uses standard HTTP methods and status codes. Parameters are passed to the API as query parameters, and the API returns JSON responses. The current version does not make use of pagination, though this may be added in the future.
28+
29+
Nixhub exposes the following endpoints for searching and resolving packages:
30+
31+
- `v2/search` - Search for packages by name
32+
- `v2/pkg` - Get details and version history for a specific package
33+
- `v2/resolve` - Resolve a package name and version to a nixpkgs commit and attribute path.
34+
35+
36+
### Rate Limits
37+
38+
In order to prevent abuse, personal use of the API is subject to rate limits. API Rate limiting works as follows:
39+
40+
1. A given IP address starts with a pool of 1000 requests
41+
2. Each request decrements the pool by 1
42+
3. The pool is replenished at a rate of 5 requests per minute
43+
44+
If the pool is empty, the API will return a `429 Too Many Requests` status code.
45+
46+
If you have a use case that requires a higher rate limit or would like to use the API for commercial purposes, please Contact Us.
47+
48+
### Versioning
49+
50+
The API is versioned using a `v2` prefix in the URL. All `v2` endpoints are considered stable and will not change in a backwards-incompatible way. Breaking changes will be introduced in a new version of the API, with a new version prefix.
51+
52+
## API Reference
53+
54+
* [Search Packages](./search-packages.api.mdx) - Search for packages by name
55+
* [Get Package Details](./get-a-package.api.mdx) - Get details and version history for a specific package
56+
* [Resolve Package](./resolve-a-package-version.api.mdx) - Resolve the latest available package for a given name and version string
57+
58+
59+

‎docs/app/docs/nixhub/resolve-a-package-version.api.mdx‎

Lines changed: 1232 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/app/docs/nixhub/search-packages.api.mdx‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
---
2+
id: search-packages
3+
title: "Search Packages"
4+
description: "Search Packages"
5+
sidebar_label: "Search Packages"
6+
hide_title: true
7+
hide_table_of_contents: true
8+
api: eJyNVe9LIzEQ/VdCPilIW8RP5X7Qg7tDDjxR75OIZnen3Wg2SZPZaln6v99MdlvXbu8oCLWZzHtv5k2mjQwQvbMRopw28nwy4Y8CYh60R+2snMrfv+SZzJ1FsMhR5b3RueLo+DnylUbGvIRK8X+49kBJLnuGHCnxI9bMijYiAniiJkhtFwJLoINYG4zCzYUSEVTIS7GsIaxH4q7UUdBfAKyDhUJk65TyNF6dj9urTwJs4Z22zOmD8xBQt0UlkJ60iIE4B9LuCLBPK1icQPcfps2ZRIfKPHbaeyQUhgWEgywpR9i6yiBwudvK5y4ksr4K5hiiqxDUethcYXRERrxNCDcdLpYKRaWQMBm+39QEJF61MSIDAZXHtdBzYd1O1CsEIGW1LUZEqBGqeITNIlKLza6UFqwnBOK+yQPbrKrgONf4JlfNxXmVv6gF9KmKg02NdVWpY+aCaildQNE73SNjOKMiPta+UAjFcao5Q6CuWCs5sRX+qqLocIS2ieZKv/mXBY+/d3LDQ6fRMHrfZgociqS3zTEKXhx63d9UIW6A2hJx2g3Ah1dwEgHJq6/Lz5/SwZfu3KtAbUcIpzJBXwyhrxyKHzw5SfQugdy939orlzxUfLk1hod9WevATcRQw37jbvdGZrB3uoZvNg//SL1u+xwpmdSUjojkAtLWUFjSl+6ZMziE1VZuHQzFSkQfp+PuyqiAVebeRrGk7SCZUdu5S2I6G8i5ss7E7PqS4BirlXI+mowmw0G7vkwroAXntahswU/HmRV/205IAZ42ENicHwo31kWslH1/MwdK/cC0axbCG469UWQA4aQSm64N97JrA1VVEgGfNE2mIvwJZrPh426vUnMKHVVm2LO5MnHftOb9x0Oe3HT2nop9Kw9qeoF1NyQrZWqOpz6vVNDMSOwPdKsEVdCuZSltwizPwWMva/CbxSg7/39+v6OJ+QsKVnKG
9+
sidebar_class_name: "get api-method"
10+
info_path: nixhub/nixhub-api
11+
custom_edit_url: null
12+
---
13+
14+
import ApiTabs from "@theme/ApiTabs";
15+
import DiscriminatorTabs from "@theme/DiscriminatorTabs";
16+
import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
17+
import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";
18+
import MimeTabs from "@theme/MimeTabs";
19+
import ParamsItem from "@theme/ParamsItem";
20+
import ResponseSamples from "@theme/ResponseSamples";
21+
import SchemaItem from "@theme/SchemaItem";
22+
import SchemaTabs from "@theme/SchemaTabs";
23+
import Markdown from "@theme/Markdown";
24+
import Heading from "@theme/Heading";
25+
import OperationTabs from "@theme/OperationTabs";
26+
import TabItem from "@theme/TabItem";
27+
28+
<Heading
29+
as={"h1"}
30+
className={"openapi__heading"}
31+
children={"Search Packages"}
32+
>
33+
</Heading>
34+
35+
<MethodEndpoint
36+
method={"get"}
37+
path={"/search"}
38+
>
39+
40+
</MethodEndpoint>
41+
42+
43+
44+
Search Packages. This endpoint allows you to search for packages in the Nixpkgs repository using a search query. The response includes a list of package names along with their description. To get available versions and installables for a package, you can use this name with the `/v2/pkg` endpoint.
45+
46+
<Heading
47+
id={"request"}
48+
as={"h2"}
49+
className={"openapi-tabs__heading"}
50+
children={"Request"}
51+
>
52+
</Heading>
53+
54+
<details
55+
style={{"marginBottom":"1rem"}}
56+
className={"openapi-markdown__details"}
57+
data-collapsed={false}
58+
open={true}
59+
>
60+
<summary
61+
style={{}}
62+
>
63+
<h3
64+
className={"openapi-markdown__details-summary-header-params"}
65+
>
66+
Query Parameters
67+
</h3>
68+
</summary><div>
69+
<ul>
70+
<ParamsItem
71+
className={"paramsItem"}
72+
param={{"name":"q","in":"query","required":true,"description":"Search query.","schema":{"type":"string"}}}
73+
>
74+
75+
</ParamsItem>
76+
</ul>
77+
</div>
78+
</details><div>
79+
<div>
80+
<ApiTabs
81+
label={undefined}
82+
id={undefined}
83+
>
84+
<TabItem
85+
label={"200"}
86+
value={"200"}
87+
>
88+
<div>
89+
90+
91+
OK
92+
93+
94+
</div><div>
95+
<MimeTabs
96+
className={"openapi-tabs__mime"}
97+
schemaType={"response"}
98+
>
99+
<TabItem
100+
label={"application/json"}
101+
value={"application/json"}
102+
>
103+
<SchemaTabs
104+
className={"openapi-tabs__schema"}
105+
>
106+
<TabItem
107+
label={"Schema"}
108+
value={"Schema"}
109+
>
110+
<details
111+
style={{}}
112+
className={"openapi-markdown__details response"}
113+
data-collapsed={false}
114+
open={true}
115+
>
116+
<summary
117+
style={{}}
118+
className={"openapi-markdown__details-summary-response"}
119+
>
120+
<strong>
121+
Schema
122+
</strong>
123+
</summary><div
124+
style={{"textAlign":"left","marginLeft":"1rem"}}
125+
>
126+
127+
</div><ul
128+
style={{"marginLeft":"1rem"}}
129+
>
130+
<SchemaItem
131+
collapsible={false}
132+
name={"query"}
133+
required={false}
134+
schemaName={"string"}
135+
qualifierMessage={undefined}
136+
schema={{"type":"string","description":"The search query sent to the `/v2/search` endpoint"}}
137+
>
138+
139+
</SchemaItem><SchemaItem
140+
collapsible={false}
141+
name={"total_results"}
142+
required={false}
143+
schemaName={"integer"}
144+
qualifierMessage={undefined}
145+
schema={{"type":"integer","description":"The total number of results for the search query"}}
146+
>
147+
148+
</SchemaItem><SchemaItem
149+
collapsible={true}
150+
className={"schemaItem"}
151+
>
152+
<details
153+
style={{}}
154+
className={"openapi-markdown__details"}
155+
>
156+
<summary
157+
style={{}}
158+
>
159+
<span
160+
className={"openapi-schema__container"}
161+
>
162+
<strong
163+
className={"openapi-schema__property"}
164+
>
165+
results
166+
</strong><span
167+
className={"openapi-schema__name"}
168+
>
169+
object[]
170+
</span>
171+
</span>
172+
</summary><div
173+
style={{"marginLeft":"1rem"}}
174+
>
175+
<div
176+
style={{"marginTop":".5rem","marginBottom":".5rem"}}
177+
>
178+
179+
180+
A list of SearchResults that match the query. This array will be empty if no results were found.
181+
182+
183+
</div><li>
184+
<div
185+
style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem","paddingBottom":".5rem"}}
186+
>
187+
Array [
188+
</div>
189+
</li><SchemaItem
190+
collapsible={false}
191+
name={"name"}
192+
required={false}
193+
schemaName={"string"}
194+
qualifierMessage={undefined}
195+
schema={{"type":"string","description":"The name of the package that matched the search query"}}
196+
>
197+
198+
</SchemaItem><SchemaItem
199+
collapsible={false}
200+
name={"summary"}
201+
required={false}
202+
schemaName={"string"}
203+
qualifierMessage={undefined}
204+
schema={{"type":"string","description":"A short description of the package"}}
205+
>
206+
207+
</SchemaItem><SchemaItem
208+
collapsible={false}
209+
name={"last_updated"}
210+
required={false}
211+
schemaName={"string"}
212+
qualifierMessage={undefined}
213+
schema={{"type":"string","description":"The last time this package was updated in the Nixpkgs repo"}}
214+
>
215+
216+
</SchemaItem><li>
217+
<div
218+
style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem"}}
219+
>
220+
]
221+
</div>
222+
</li>
223+
</div>
224+
</details>
225+
</SchemaItem>
226+
</ul>
227+
</details>
228+
</TabItem><TabItem
229+
label={"Example (from schema)"}
230+
value={"Example (from schema)"}
231+
>
232+
<ResponseSamples
233+
responseExample={"{\n \"query\": \"string\",\n \"total_results\": 0,\n \"results\": [\n {\n \"name\": \"string\",\n \"summary\": \"string\",\n \"last_updated\": \"string\"\n }\n ]\n}"}
234+
language={"json"}
235+
>
236+
237+
</ResponseSamples>
238+
</TabItem>
239+
</SchemaTabs>
240+
</TabItem>
241+
</MimeTabs>
242+
</div>
243+
</TabItem><TabItem
244+
label={"400"}
245+
value={"400"}
246+
>
247+
<div>
248+
249+
250+
Bad Request: empty search query (set a ?q=&lt;query&gt; query parameter)
251+
252+
253+
</div><div>
254+
255+
</div>
256+
</TabItem><TabItem
257+
label={"404"}
258+
value={"404"}
259+
>
260+
<div>
261+
262+
263+
Not Found
264+
265+
266+
</div><div>
267+
268+
</div>
269+
</TabItem>
270+
</ApiTabs>
271+
</div>
272+
</div>
273+

‎docs/app/docs/nixhub/sidebar.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
2+
3+
const nixhubSidebar: SidebarsConfig = {
4+
sidebar:
5+
[
6+
{
7+
type: "doc",
8+
label: "Get a Package",
9+
id: "nixhub/get-a-package",
10+
},
11+
{
12+
type: "doc",
13+
label: "Search Packages",
14+
id: "nixhub/search-packages",
15+
},
16+
{
17+
type: "doc",
18+
label: "Resolve a Package",
19+
id: "nixhub/resolve-a-package-version",
20+
}
21+
]
22+
}
23+
24+
export default nixhubSidebar.sidebar;

0 commit comments

Comments
 (0)