Skip to content

Commit 46be49a

Browse files
kai687kai687
authored
docs(specs): align with style guides (#5930)
1 parent 7c45861 commit 46be49a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+233
-213
lines changed

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,10 @@ yarn cli release --dry-run # Test release without pushing
142142

143143
## NOTES
144144

145+
### API Documentation Guidelines
146+
147+
When writing or editing API specs, follow `website/docs/add-a-new-api/api-documentation-guidelines.md`.
148+
145149
### Docker Required
146150

147151
Most language builds require Docker. Run `yarn docker:setup` first. Images: `apic_base` (most languages), `apic_ruby`, `apic_swift`.

‎specs/abtesting-v3/spec.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ info:
88
description: |
99
## Base URLs
1010
11-
The base URLs for requests to the A/B testing API are:
11+
Base URLs for the A/B testing API:
1212
1313
- `https://analytics.us.algolia.com`
1414
- `https://analytics.de.algolia.com`
@@ -22,7 +22,7 @@ info:
2222
2323
Access to the A/B testing API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing).
2424
25-
To authenticate your API requests, add these headers:
25+
Add these headers to authenticate requests:
2626
2727
- `x-algolia-application-id`. Your Algolia application ID.
2828
- `x-algolia-api-key`. An API key with the necessary permissions to make the request.
@@ -46,12 +46,12 @@ info:
4646
The A/B testing API returns JSON responses.
4747
Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
4848
49-
Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
49+
Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.
5050
Error responses have a `message` property with more information.
5151
5252
## Version
5353
54-
The current version of the A/B Testing API is version 3, as indicated by the `/3/` in each endpoint's URL.
54+
The current version of the A/B Testing API is version 3, indicated by the `/3/` in each endpoint's URL.
5555
version: 3.0.0
5656
components:
5757
securitySchemes:

‎specs/abtesting/spec.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ info:
88
description: |
99
## Base URLs
1010
11-
The base URLs for requests to the A/B testing API are:
11+
Base URLs for the A/B testing API:
1212
1313
- `https://analytics.us.algolia.com`
1414
- `https://analytics.de.algolia.com`
@@ -22,7 +22,7 @@ info:
2222
2323
Access to the A/B testing API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing).
2424
25-
To authenticate your API requests, add these headers:
25+
Add these headers to authenticate requests:
2626
2727
- `x-algolia-application-id`. Your Algolia application ID.
2828
- `x-algolia-api-key`. An API key with the necessary permissions to make the request.
@@ -46,12 +46,12 @@ info:
4646
The A/B testing API returns JSON responses.
4747
Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
4848
49-
Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
49+
Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.
5050
Error responses have a `message` property with more information.
5151
5252
## Version
5353
54-
The current version of the A/B Testing API is version 2, as indicated by the `/2/` in each endpoint's URL.
54+
The current version of the A/B Testing API is version 2, indicated by the `/2/` in each endpoint's URL.
5555
version: 2.0.0
5656
components:
5757
securitySchemes:

‎specs/advanced-personalization/common/schemas/UsersParams.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
startDate:
33
name: startDate
44
description: |
5-
Filter users by start date (in RFC3339 format).
5+
Filter users by start date and time, in RFC 3339 format.
66
Only users that were updated after the passed date will be returned.
77
in: query
88
schema:
@@ -12,7 +12,7 @@ startDate:
1212
endDate:
1313
name: endDate
1414
description: |
15-
Filter users by end date (in RFC3339 format).
15+
Filter users by end date and time, in RFC 3339 format.
1616
Only users that were updated before the passed date will be returned.
1717
in: query
1818
schema:

‎specs/advanced-personalization/spec.yml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ info:
88
Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps.
99
The official API clients are covered by Algolia's [Service Level Agreement](https://www.algolia.com/policies/sla).
1010
11-
See: [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem)
11+
For more information, see [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem).
1212
1313
## Base URLs
1414
@@ -23,7 +23,7 @@ info:
2323
2424
## Authentication
2525
26-
To authenticate your API requests, add these headers:
26+
Add these headers to authenticate requests:
2727
2828
- `x-algolia-application-id`. Your Algolia application ID.
2929
- `x-algolia-api-key`. An API key with the `search`, `browse` and `recommendation` ACL permissions.
@@ -39,7 +39,7 @@ info:
3939
The Advanced Personalization API returns JSON responses.
4040
Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
4141
42-
Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
42+
Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.
4343
Error responses have a `message` property with more information.
4444
4545
## Rate limiting
@@ -50,11 +50,11 @@ info:
5050
5151
- `x-ratelimit-limit`: The number of requests allowed every 60 seconds.
5252
- `x-ratelimit-remaining`: The number of requests remaining in the current 60 second period.
53-
- `x-ratelimit-reset`: [Unix timestamp](https://www.unixtimestamp.com) of the next time period.
53+
- `x-ratelimit-reset`: Timestamp when the next time period starts, measured in seconds since the Unix epoch.
5454
5555
## Version
5656
57-
The current version of the Advanced Personalization API is version 2, as indicated by the `/2/` in each endpoint's URL.
57+
The current version of the Advanced Personalization API is version 2, indicated by the `/2/` in each endpoint's URL.
5858
version: 2.0.0
5959
components:
6060
securitySchemes:

‎specs/analytics/paths/click/getPurchaseRate.yml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,16 @@ get:
88
description: |
99
Retrieves the purchase rate for all your searches with at least one purchase event, including a daily breakdown.
1010
11-
By default, the analyzed period includes the last eight days including the current day.
11+
By default, the analyzed period includes the last eight days, including the current day.
1212
13-
The rate is the number of purchase conversion events divided by the number of tracked searches.
13+
The rate is purchase conversion events divided by tracked searches.
1414
A search is tracked if it returns a query ID (`clickAnalytics` is `true`).
15-
This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
15+
This differs from the response's `count`, which includes searches where `clickAnalytics` is `false`.
1616
1717
**There's a difference between a 0 and null purchase rate when `clickAnalytics` is enabled:**
1818
19-
- **Null** means there were no queries: since Algolia didn't receive any events, the purchase rate is null.
20-
- **0** mean there _were_ queries but no [purchase conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started) were received.
19+
- **Null** means there were no queries. Algolia didn't receive any events, so the purchase rate is null.
20+
- **0** means there were queries but no [purchase conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started) were received.
2121
parameters:
2222
- $ref: '../../../common/parameters.yml#/Index'
2323
- $ref: '../../../common/parameters.yml#/StartDate'

‎specs/analytics/paths/search/getTopHits.yml‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,11 @@ get:
99
description: |
1010
Retrieves the object IDs of the 1,000 most frequent search results.
1111
12-
If you set the `clickAnalytics` query parameter to true, the response also includes:
12+
If you set the `clickAnalytics` query parameter to `true`, the response also includes:
1313
14-
- Tracked searches count. Tracked searches are Search API requests with the `clickAnalytics` parameter set to `true`. This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
14+
- Tracked searches count.
15+
Tracked searches are Search API requests with `clickAnalytics` set to `true`.
16+
This differs from the response's `count`, which includes searches where `clickAnalytics` is `false`.
1517
- Click count
1618
- Click-through rate (CTR)
1719
- Conversion count
@@ -28,8 +30,8 @@ get:
2830
2931
**There's a difference between 0% rates and null rates:**
3032
31-
- **Null** means there were no queries: since Algolia didn't receive any events, the rates (CTR, CR, ATCR, purchase rate) are null.
32-
- **0% rates** mean there _were_ queries but no [click or conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started) were received.
33+
- **Null** means there were no queries. Algolia didn't receive any events, so rates are null.
34+
- **0% rates** mean there were queries but no [click or conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started) were received.
3335
parameters:
3436
- $ref: '../../../common/parameters.yml#/Index'
3537
- $ref: '../../common/parameters.yml#/Search'

‎specs/analytics/paths/search/getTopSearches.yml‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,11 @@ get:
99
description: |
1010
Returns the most popular searches. For each search, it also includes the average number of hits.
1111
12-
If you set the `clickAnalytics` query parameter to `true`, the response also includes
12+
If you set the `clickAnalytics` query parameter to `true`, the response also includes:
1313
14-
- Tracked searches count. Tracked searches are Search API requests with the `clickAnalytics` parameter set to `true`. This differs from the response's `count`, which shows the overall number of searches, including those where `clickAnalytics` is `false`.
14+
- Tracked searches count
15+
Tracked searches are Search API requests with `clickAnalytics` set to `true`.
16+
This differs from the response's `count`, which includes searches where `clickAnalytics` is `false`.
1517
- Click count
1618
- Click-through rate (CTR)
1719
- Conversion count
@@ -28,8 +30,8 @@ get:
2830
2931
**There's a difference between 0% rates and null rates:**
3032
31-
- **Null** means there were no queries: since Algolia didn't receive any events, the rates (CTR, CR, ATCR, purchase rate) are null.
32-
- **0% rates** mean there _were_ queries but no [click or conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started) were received.
33+
- **Null** means there were no queries. Algolia didn't receive any events, so rates are null.
34+
- **0% rates** mean there were queries but no [click or conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started) were received.
3335
parameters:
3436
- $ref: '../../../common/parameters.yml#/Index'
3537
- $ref: '../../common/parameters.yml#/ClickAnalytics'

‎specs/analytics/spec.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ info:
88
description: |
99
## Base URLs
1010
11-
The base URLs for requests to the Analytics API are:
11+
Base URLs for the Analytics API:
1212
1313
- `https://analytics.us.algolia.com`
1414
- `https://analytics.de.algolia.com`
@@ -22,7 +22,7 @@ info:
2222
2323
Access to the Analytics API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing).
2424
25-
To authenticate your API requests, add these headers:
25+
Add these headers to authenticate requests:
2626
2727
- `x-algolia-application-id`. Your Algolia application ID.
2828
- `x-algolia-api-key`. An API key with the necessary permissions to make the request.
@@ -54,7 +54,7 @@ info:
5454
5555
## Version
5656
57-
The current version of the Analytics API is version 2, as indicated by the `/2/` in each endpoint's URL.
57+
The current version of the Analytics API is version 2, indicated by the `/2/` in each endpoint's URL.
5858
5959
## Query aggregation
6060

‎specs/common/helpers/setClientApiKey.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ method:
1212
parameters:
1313
- in: query
1414
name: apiKey
15-
description: API key to be used from now on.
15+
description: API key to use for subsequent requests.
1616
required: true
1717
schema:
1818
type: string

0 commit comments

Comments
 (0)