Skip to content

Commit 72278bb

Browse files
basit3407basit3407
authored
[codex] add code examples and scoped AI prompts to Content APIs quickstart child guides (#108)
* [codex] add code examples and ai prompts to content quickstart child docs * [codex] tighten content quickstart child code examples * [codex] collapse child quickstart examples and add node parity * [codex] fix child quickstart accordion scope and env validation
1 parent ac25b97 commit 72278bb

4 files changed

Lines changed: 577 additions & 0 deletions

File tree

‎docs/quickstart/first-api-call.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ keywords:
77
- "x-client-id"
88
- "chapters endpoint"
99
- "backend proxy"
10+
- "Python requests chapters example"
11+
- "Node fetch chapters example"
1012
sidebar_label: "First API Call"
1113
displayed_sidebar: "APIsSidebar"
1214
---
@@ -37,6 +39,80 @@ curl --request GET \
3739
--header "x-client-id: YOUR_CLIENT_ID"
3840
```
3941

42+
<details>
43+
<summary><b>Expand for Python and Node.js request examples</b></summary>
44+
45+
### Python Example (`requests`)
46+
47+
```python
48+
import os
49+
50+
import requests
51+
52+
API_BASE_BY_ENV = {
53+
"production": "https://apis.quran.foundation",
54+
"prelive": "https://apis-prelive.quran.foundation",
55+
}
56+
env = os.getenv("QF_ENV", "prelive")
57+
if env not in API_BASE_BY_ENV:
58+
raise ValueError(
59+
f"Invalid QF_ENV value: {env!r}. Expected 'prelive' or 'production'."
60+
)
61+
62+
API_BASE_URL = API_BASE_BY_ENV[env]
63+
access_token = "YOUR_ACCESS_TOKEN" # Replace with your token helper or prior manual-auth step.
64+
65+
response = requests.get(
66+
f"{API_BASE_URL}/content/api/v4/chapters",
67+
headers={
68+
"x-auth-token": access_token,
69+
"x-client-id": os.environ["QF_CLIENT_ID"],
70+
},
71+
timeout=30,
72+
)
73+
response.raise_for_status()
74+
75+
data = response.json()
76+
print(data["chapters"][0]["name_simple"])
77+
```
78+
79+
This example uses `YOUR_ACCESS_TOKEN` as a placeholder. In production, reuse your token helper or cache from the [manual authentication](/docs/quickstart/manual-authentication) step instead of exporting one-off token environment variables.
80+
81+
### Node.js Example (`fetch`)
82+
83+
This example assumes Node 18+ or another runtime with a global `fetch` implementation.
84+
85+
```js
86+
async function listChapters() {
87+
const apiBaseByEnv = {
88+
production: "https://apis.quran.foundation",
89+
prelive: "https://apis-prelive.quran.foundation",
90+
};
91+
const env = process.env.QF_ENV ?? "prelive";
92+
if (!(env in apiBaseByEnv)) {
93+
throw new Error("QF_ENV must be 'prelive' or 'production'");
94+
}
95+
96+
const apiBaseUrl = apiBaseByEnv[env];
97+
98+
const response = await fetch(`${apiBaseUrl}/content/api/v4/chapters`, {
99+
headers: {
100+
"x-auth-token": "YOUR_ACCESS_TOKEN",
101+
"x-client-id": process.env.QF_CLIENT_ID,
102+
},
103+
});
104+
105+
if (!response.ok) {
106+
throw new Error(`Chapters request failed: ${response.status}`);
107+
}
108+
109+
const data = await response.json();
110+
console.log(data.chapters[0].name_simple);
111+
}
112+
```
113+
114+
</details>
115+
40116
### Example Successful Response
41117
42118
```json
@@ -73,6 +149,31 @@ const response = await fetch("/chapters");
73149
const data = await response.json();
74150
```
75151
152+
## AI Handoff Prompt
153+
154+
Use this prompt when you want an AI coding tool to wire up the first authenticated Content API request:
155+
156+
<details>
157+
<summary><b>Expand AI handoff prompt</b></summary>
158+
159+
```text
160+
Implement the first authenticated Quran Foundation Content API call on the backend.
161+
162+
Requirements
163+
- Call GET /content/api/v4/chapters against the correct prelive or production base URL.
164+
- Send both required headers: x-auth-token and x-client-id.
165+
- Reuse the existing backend token helper instead of requesting a new token for every request.
166+
- Expose a backend route or service method that returns the chapters response without leaking credentials to the frontend.
167+
- Verify success by checking that the response contains a chapters array.
168+
169+
Documentation to follow
170+
- First API call: https://api-docs.quran.foundation/docs/quickstart/first-api-call
171+
- Token management: https://api-docs.quran.foundation/docs/quickstart/token-management
172+
- Content API reference: https://api-docs.quran.foundation/docs/category/content-apis
173+
```
174+
175+
</details>
176+
76177
## Verification Checklist
77178
78179
- The request returns JSON with a `chapters` array.

‎docs/quickstart/manual-authentication.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ keywords:
66
- "client credentials"
77
- "manual authentication"
88
- "content scope"
9+
- "Python requests token request"
10+
- "Node fetch client credentials"
911
sidebar_label: "Manual Authentication"
1012
displayed_sidebar: "APIsSidebar"
1113
---
@@ -57,6 +59,101 @@ curl --request POST \
5759
--data 'grant_type=client_credentials&scope=content'
5860
```
5961

62+
<details>
63+
<summary><b>Expand for Python and Node.js token request examples</b></summary>
64+
65+
### Python Example (`requests`)
66+
67+
```python
68+
import os
69+
70+
import requests
71+
from requests.auth import HTTPBasicAuth
72+
73+
AUTH_BASE_BY_ENV = {
74+
"prelive": "https://prelive-oauth2.quran.foundation",
75+
"production": "https://oauth2.quran.foundation",
76+
}
77+
78+
env = os.getenv("QF_ENV", "prelive")
79+
if env not in AUTH_BASE_BY_ENV:
80+
raise ValueError(
81+
f"Invalid QF_ENV value: {env!r}. Expected 'prelive' or 'production'."
82+
)
83+
84+
AUTH_BASE_URL = AUTH_BASE_BY_ENV[env]
85+
86+
response = requests.post(
87+
f"{AUTH_BASE_URL}/oauth2/token",
88+
auth=HTTPBasicAuth(
89+
os.environ["QF_CLIENT_ID"],
90+
os.environ["QF_CLIENT_SECRET"],
91+
),
92+
headers={"Content-Type": "application/x-www-form-urlencoded"},
93+
data={
94+
"grant_type": "client_credentials",
95+
"scope": "content",
96+
},
97+
timeout=30,
98+
)
99+
response.raise_for_status()
100+
101+
token = response.json()
102+
access_token = token["access_token"]
103+
expires_in = token["expires_in"]
104+
```
105+
106+
### Node.js Example (`fetch`)
107+
108+
This example assumes Node 18+ or another runtime with a global `fetch` implementation.
109+
110+
```js
111+
async function getToken() {
112+
const authBaseByEnv = {
113+
production: "https://oauth2.quran.foundation",
114+
prelive: "https://prelive-oauth2.quran.foundation",
115+
};
116+
const env = process.env.QF_ENV ?? "prelive";
117+
if (!(env in authBaseByEnv)) {
118+
throw new Error("QF_ENV must be 'prelive' or 'production'");
119+
}
120+
121+
const authBaseUrl = authBaseByEnv[env];
122+
123+
const basicAuth = Buffer.from(
124+
`${process.env.QF_CLIENT_ID}:${process.env.QF_CLIENT_SECRET}`,
125+
).toString("base64");
126+
127+
const response = await fetch(`${authBaseUrl}/oauth2/token`, {
128+
method: "POST",
129+
headers: {
130+
Authorization: `Basic ${basicAuth}`,
131+
"Content-Type": "application/x-www-form-urlencoded",
132+
},
133+
body: new URLSearchParams({
134+
grant_type: "client_credentials",
135+
scope: "content",
136+
}),
137+
});
138+
139+
if (!response.ok) {
140+
throw new Error(`Token request failed: ${response.status}`);
141+
}
142+
143+
return response.json();
144+
}
145+
146+
getToken()
147+
.then(({ expires_in }) => {
148+
console.log("Fetched token that expires in", expires_in, "seconds");
149+
})
150+
.catch((error) => {
151+
console.error("Token request failed:", error);
152+
});
153+
```
154+
155+
</details>
156+
60157
### Sample Token Response
61158
62159
```json
@@ -81,6 +178,30 @@ Recommended pattern:
81178
3. Use the token when your backend calls the Content APIs.
82179
4. Return only the API data your frontend needs.
83180
181+
## AI Handoff Prompt
182+
183+
Use this prompt when you want an AI coding tool to implement manual token retrieval on your backend:
184+
185+
<details>
186+
<summary><b>Expand AI handoff prompt</b></summary>
187+
188+
```text
189+
Implement Quran Foundation Content API token retrieval on the backend.
190+
191+
Requirements
192+
- Read QF_CLIENT_ID, QF_CLIENT_SECRET, and QF_ENV from environment variables.
193+
- Use prelive -> https://prelive-oauth2.quran.foundation and production -> https://oauth2.quran.foundation.
194+
- Request POST /oauth2/token with HTTP Basic auth, grant_type=client_credentials, and scope=content.
195+
- Return access_token and expires_in from the token response.
196+
- Do not expose client_secret to browser or mobile code.
197+
198+
Documentation to follow
199+
- Manual authentication: https://api-docs.quran.foundation/docs/quickstart/manual-authentication
200+
- Token management: https://api-docs.quran.foundation/docs/quickstart/token-management
201+
```
202+
203+
</details>
204+
84205
## Continue the Manual Flow
85206
86207
- [Token management](/docs/quickstart/token-management) for caching, early re-requesting, and 401 retry behavior.

‎docs/quickstart/migration.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ keywords:
66
- "Quran Foundation Content APIs"
77
- "OAuth2 migration"
88
- "client credentials migration"
9+
- "Python requests migration example"
10+
- "Node fetch migration example"
911
sidebar_label: "Migration"
1012
displayed_sidebar: "APIsSidebar"
1113
---
@@ -41,13 +43,122 @@ The main changes are the base URL and authentication model. The endpoints, query
4143
5. Add `x-auth-token` and `x-client-id` to every Content API request.
4244
6. Verify the migration with `GET /content/api/v4/chapters`.
4345

46+
## Before and After Example
47+
48+
Older unauthenticated request:
49+
50+
```bash
51+
curl --request GET \
52+
--url https://api.quran.com/api/v4/chapters
53+
```
54+
55+
Updated authenticated request (replace `{apiBaseUrl}` with your prelive or production Content API base URL):
56+
57+
```bash
58+
curl --request GET \
59+
--url {apiBaseUrl}/content/api/v4/chapters \
60+
--header "x-auth-token: YOUR_ACCESS_TOKEN" \
61+
--header "x-client-id: YOUR_CLIENT_ID"
62+
```
63+
64+
<details>
65+
<summary><b>Expand for Python and Node.js migration examples</b></summary>
66+
67+
Python migration example:
68+
69+
```python
70+
import os
71+
72+
import requests
73+
74+
API_BASE_BY_ENV = {
75+
"production": "https://apis.quran.foundation",
76+
"prelive": "https://apis-prelive.quran.foundation",
77+
}
78+
env = os.getenv("QF_ENV", "prelive")
79+
if env not in API_BASE_BY_ENV:
80+
raise ValueError(
81+
f"Invalid QF_ENV value: {env!r}. Expected 'prelive' or 'production'."
82+
)
83+
84+
API_BASE_URL = API_BASE_BY_ENV[env]
85+
access_token = "YOUR_ACCESS_TOKEN" # Replace with your token helper or prior manual-auth step.
86+
87+
response = requests.get(
88+
f"{API_BASE_URL}/content/api/v4/chapters",
89+
headers={
90+
"x-auth-token": access_token,
91+
"x-client-id": os.environ["QF_CLIENT_ID"],
92+
},
93+
timeout=30,
94+
)
95+
response.raise_for_status()
96+
```
97+
98+
Node.js migration example:
99+
100+
```js
101+
async function fetchChapters() {
102+
const apiBaseByEnv = {
103+
production: "https://apis.quran.foundation",
104+
prelive: "https://apis-prelive.quran.foundation",
105+
};
106+
const env = process.env.QF_ENV ?? "prelive";
107+
if (!(env in apiBaseByEnv)) {
108+
throw new Error("QF_ENV must be 'prelive' or 'production'");
109+
}
110+
111+
const apiBaseUrl = apiBaseByEnv[env];
112+
113+
const response = await fetch(`${apiBaseUrl}/content/api/v4/chapters`, {
114+
headers: {
115+
"x-auth-token": "YOUR_ACCESS_TOKEN",
116+
"x-client-id": process.env.QF_CLIENT_ID,
117+
},
118+
});
119+
120+
if (!response.ok) {
121+
throw new Error(`Migration check failed: ${response.status}`);
122+
}
123+
124+
return response.json();
125+
}
126+
```
127+
128+
</details>
129+
44130
## Compatibility Notes
45131
46132
- Tokens are environment-specific. Do not use prelive tokens against production or the reverse.
47133
- This quickstart flow does not use refresh tokens. Re-request the access token instead.
48134
- A `403` usually points to missing permissions or the wrong scope. Use `scope=content`.
49135
- A `401` usually means the token expired or was invalid. Re-request once and retry once.
50136
137+
## AI Handoff Prompt
138+
139+
Use this prompt when you want an AI coding tool to update an older `api.quran.com` integration:
140+
141+
<details>
142+
<summary><b>Expand AI handoff prompt</b></summary>
143+
144+
```text
145+
Migrate an existing api.quran.com Content API integration to Quran Foundation Content APIs.
146+
147+
Requirements
148+
- Replace the old base URL with the correct Quran Foundation prelive or production base URL.
149+
- Add backend-only OAuth2 Client Credentials token retrieval with scope=content.
150+
- Add x-auth-token and x-client-id to every Content API request.
151+
- Preserve existing endpoint paths, query parameters, and response handling where the API contract is unchanged.
152+
- Verify the migration with GET /content/api/v4/chapters.
153+
154+
Documentation to follow
155+
- Migration guide: https://api-docs.quran.foundation/docs/quickstart/migration
156+
- Manual authentication: https://api-docs.quran.foundation/docs/quickstart/manual-authentication
157+
- First API call: https://api-docs.quran.foundation/docs/quickstart/first-api-call
158+
```
159+
160+
</details>
161+
51162
## Related Docs
52163
53164
- [Manual authentication](/docs/quickstart/manual-authentication) for credentials and token requests.

0 commit comments

Comments
 (0)