From 7c8abd62f06f3a69aa3b106f8f22f31b5f49933f Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Sun, 7 Apr 2024 11:55:05 +0200 Subject: [PATCH 1/3] fix(specs): update descriptions --- specs/analytics/common/parameters.yml | 2 +- specs/analytics/spec.yml | 14 +- specs/common/parameters.yml | 22 +- specs/common/responses/common.yml | 22 +- specs/common/schemas/IndexSettings.yml | 218 +++++++----------- specs/crawler/common/parameters.yml | 5 - .../schemas/crawlerConfigVersionsResponse.yml | 2 +- .../common/schemas/getCrawlerResponse.yml | 15 +- specs/crawler/paths/crawlerConfigVersion.yml | 2 +- specs/crawler/paths/crawlerTest.yml | 4 +- .../ingestion/common/schemas/destination.yml | 11 +- specs/ingestion/common/schemas/task.yml | 35 +-- specs/ingestion/spec.yml | 14 +- .../common/schemas/EventAttributes.yml | 2 +- specs/insights/spec.yml | 12 +- specs/monitoring/common/schemas/Timestamp.yml | 2 +- specs/monitoring/spec.yml | 10 +- .../paths/getConfigurationStatus.yml | 4 +- specs/query-suggestions/paths/getLogFile.yml | 2 +- specs/query-suggestions/spec.yml | 14 +- specs/search/common/parameters.yml | 14 +- .../search/helpers/generateSecuredApiKey.yml | 4 +- specs/search/paths/advanced/getLogs.yml | 2 +- specs/search/paths/objects/objects.yml | 4 +- specs/search/spec.yml | 14 +- specs/usage/common/parameters.yml | 43 ++-- specs/usage/common/schemas/responses.yml | 2 +- specs/usage/paths/statistic.yml | 4 +- specs/usage/paths/statisticIndex.yml | 4 +- specs/usage/spec.yml | 8 +- 30 files changed, 197 insertions(+), 314 deletions(-) diff --git a/specs/analytics/common/parameters.yml b/specs/analytics/common/parameters.yml index 6f9e027246..b993f83e7e 100644 --- a/specs/analytics/common/parameters.yml +++ b/specs/analytics/common/parameters.yml @@ -316,7 +316,7 @@ x-ratelimit-remaining: type: integer x-ratelimit-reset: - description: Timestamp in Unix epoch time when the rate limit will reset. + description: Timstamp when the rate limit will reset, measured in seconds since the Unix epoch. example: 1710682486 schema: type: integer diff --git a/specs/analytics/spec.yml b/specs/analytics/spec.yml index cc50adee2e..5c1af4f1fb 100644 --- a/specs/analytics/spec.yml +++ b/specs/analytics/spec.yml @@ -14,7 +14,7 @@ info: # Base URLs - The base URLs for making requests to the Analytics API are: + The base URLs for requests to the Analytics API are: - `https://analytics.us.algolia.com` (alias: `https://analytics.algolia.com`) - `https://analytics.de.algolia.com` @@ -27,15 +27,9 @@ info: To authenticate your API requests, add these headers: -
-
x-algolia-application-id
-
Your Algolia application ID.
-
x-algolia-api-key
-
- An API key with the necessary permissions to make the request. - The required access control list (ACL) to make a request is listed in each endpoint's reference. -
-
+ - `x-algolia-application-id`. Your Algolia application ID. + - `x-algolia-api-key`. An API key with the necessary permissions to make the request. + The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). diff --git a/specs/common/parameters.yml b/specs/common/parameters.yml index 25bc9e4ee4..400a70e299 100644 --- a/specs/common/parameters.yml +++ b/specs/common/parameters.yml @@ -30,7 +30,16 @@ Index: StartDate: in: query name: startDate - description: Start date (`YYYY-MM-DD`) of the period to analyze. + description: Start date of the period to analyze, in `YYYY-MM-DD` format. + schema: + type: string + example: 2022-09-19 + +StartDateRequired: + in: query + name: startDate + description: Start date of the period to analyze, in `YYYY-MM-DD` format. + required: true schema: type: string example: 2022-09-19 @@ -38,7 +47,16 @@ StartDate: EndDate: in: query name: endDate - description: End date (`YYYY-MM-DD`) of the period to analyze. + description: End date of the period to analyze, in `YYYY-MM-DD` format. + schema: + type: string + example: 2023-01-21 + +EndDateRequired: + in: query + name: endDate + description: End date of the period to analyze, in `YYYY-MM-DD` format. + required: true schema: type: string example: 2023-01-21 diff --git a/specs/common/responses/common.yml b/specs/common/responses/common.yml index 6595d40682..8fb8e4dfe2 100644 --- a/specs/common/responses/common.yml +++ b/specs/common/responses/common.yml @@ -19,28 +19,30 @@ objectIDs: createdAt: type: string example: 2023-07-04T12:49:15Z - description: Timestamp of creation in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. + description: Date and time when the object was created, in RFC 3339 format. createdAtTimestamp: type: integer format: int64 example: 1656345570000 - description: Timestamp of creation in milliseconds in [Unix epoch time](https://wikipedia.org/wiki/Unix_time). + description: Timestamp when the object was created, in milliseconds since the Unix epoch. updatedAt: type: string example: 2023-07-04T12:49:15Z - description: Timestamp of the last update in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. + description: Date and time when the object was updated, in RFC 3339 format. updatedAtNullable: - type: string - example: 2023-07-04T12:49:15Z - nullable: true - description: | - Timestamp of the last update in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. - If null, no update was performed yet. + default: null + oneOf: + - type: string + example: 2023-07-04T12:49:15Z + description: | + Date and time when the object was updated, in RFC 3339 format. + - type: 'null' + description: If null, this object wasn't updated yet. deletedAt: type: string example: 2023-06-27T14:42:38.831Z - description: Timestamp of deletion in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. + description: Date and time when the object was deleted, in RFC 3339 format. diff --git a/specs/common/schemas/IndexSettings.yml b/specs/common/schemas/IndexSettings.yml index 5911169358..33dfec6307 100644 --- a/specs/common/schemas/IndexSettings.yml +++ b/specs/common/schemas/IndexSettings.yml @@ -28,22 +28,16 @@ baseIndexSettings: **Modifiers** -
-
filterOnly("ATTRIBUTE")
-
Allows using this attribute as a filter, but doesn't evalue the facet values.
-
searchable("ATTRIBUTE")
-
Allows searching for facet values.
-
afterDistinct("ATTRIBUTE")
-
- - Evaluates the facet count _after_ deduplication with `distinct`. - This ensures accurate facet counts. - You can apply this modifier to searchable facets: `afterDistinct(searchable(ATTRIBUTE))`. - -
-
- - Without modifiers, the attribute is used as a regular facet. + - `filterOnly("ATTRIBUTE")`. + Allows using this attribute as a filter, but doesn't evalue the facet values. + + - `searchable("ATTRIBUTE")`. + Allows searching for facet values. + + - `afterDistinct("ATTRIBUTE")`. + Evaluates the facet count _after_ deduplication with `distinct`. + This ensures accurate facet counts. + You can apply this modifier to searchable facets: `afterDistinct(searchable(ATTRIBUTE))`. default: [] x-categories: - Faceting @@ -63,17 +57,9 @@ baseIndexSettings: **Modifier** -
-
virtual("REPLICA")
-
- - Create a virtual replica, - Virtual replicas don't increase the number of records and are optimized for [Relevant sorting](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/relevant-sort/). - -
-
- - Without modifier, a standard replica is created, which duplicates your record count and is used for strict, or [exhaustive sorting](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/exhaustive-sort/). + - `virtual("REPLICA")`. + Create a virtual replica, + Virtual replicas don't increase the number of records and are optimized for [Relevant sorting](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/relevant-sort/). default: [] x-categories: - Ranking @@ -204,16 +190,8 @@ baseIndexSettings: **Modifier** -
-
equalOnly("ATTRIBUTE")
-
- - Support only filtering based on equality comparisons `=` and `!=`. - -
-
- - Without modifier, all numeric comparisons are supported. + - `equalOnly("ATTRIBUTE")`. + Support only filtering based on equality comparisons `=` and `!=`. example: - equalOnly(quantity) - popularity @@ -255,12 +233,8 @@ baseIndexSettings: **Modifier** -
-
unordered("ATTRIBUTE")
-
- Ignore the position of a match within the attribute. -
-
+ - `unordered("ATTRIBUTE")`. + Ignore the position of a match within the attribute. Without modifier, matches at the beginning of an attribute rank higer than matches at the end. default: [] @@ -333,12 +307,10 @@ indexSettingsAsSearchParams: **Modifiers** -
-
asc("ATTRIBUTE")
-
Sort the index by the values of an attribute, in ascending order.
-
desc("ATTRIBUTE")
-
Sort the index by the values of an attribute, in descending order.
-
+ - `asc("ATTRIBUTE")`. + Sort the index by the values of an attribute, in ascending order. + - `desc("ATTRIBUTE")`. + Sort the index by the values of an attribute, in descending order. Before you modify the default setting, you should test your changes in the dashboard, @@ -371,14 +343,14 @@ indexSettingsAsSearchParams: **Modifiers** -
-
asc("ATTRIBUTE")
-
Sort the index by the values of an attribute, in ascending order.
-
desc("ATTRIBUTE")
-
Sort the index by the values of an attribute, in descending order.
-
+ - `asc("ATTRIBUTE")`. + Sort the index by the values of an attribute, in ascending order. + + - `desc("ATTRIBUTE")`. + Sort the index by the values of an attribute, in descending order. - If you use two or more custom ranking attributes, [reduce the precision](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/how-to/controlling-custom-ranking-metrics-precision/) of your first attributes, + If you use two or more custom ranking attributes, + [reduce the precision](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/how-to/controlling-custom-ranking-metrics-precision/) of your first attributes, or the other attributes will never be applied. default: [] x-categories: @@ -629,22 +601,14 @@ indexSettingsAsSearchParams: description: | Alternatives of query words that should be considered as exact matches by the Exact ranking criterion. -
-
ignorePlurals
-
- - Plurals and similar declensions added by the `ignorePlurals` setting are considered exact matches. - -
-
singleWordSynonym
-
- Single-word synonyms, such as "NY/NYC" are considered exact matches. -
-
multiWordsSynonym
-
- Multi-word synonyms, such as "NY/New York" are considered exact matches. -
-
. + - `ignorePlurals`. + Plurals and similar declensions added by the `ignorePlurals` setting are considered exact matches. + + - `singleWordSynonym`. + Single-word synonyms, such as "NY/NYC" are considered exact matches. + + - `multiWordsSynonym`. + Multi-word synonyms, such as "NY/New York" are considered exact matches. default: [ignorePlurals, singleWordSynonym] x-categories: - Query strategy @@ -655,22 +619,13 @@ indexSettingsAsSearchParams: description: | Advanced search syntax features you want to support. -
-
exactPhrase
-
- - Phrases in quotes must match exactly. - For example, `sparkly blue "iPhone case"` only returns records with the exact string "iPhone case". + - `exactPhrase`. + Phrases in quotes must match exactly. + For example, `sparkly blue "iPhone case"` only returns records with the exact string "iPhone case". -
-
excludeWords
-
- - Query words prefixed with a `-` must not occur in a record. - For example, `search -engine` matches records that contain "search" but not "engine". - -
-
+ - `excludeWords`. + Query words prefixed with a `-` must not occur in a record. + For example, `search -engine` matches records that contain "search" but not "engine". This setting only has an effect if `advancedSyntax` is true. default: [exactPhrase, excludeWords] @@ -739,15 +694,12 @@ indexSettingsAsSearchParams: description: | Order in which to retrieve facet values. -
-
count
-
- Facet values are retrieved by decreasing count. - The count is the number of matching records containing this facet value. -
-
alpha
-
Retrieve facet values alphabetically.
-
+ - `count`. + Facet values are retrieved by decreasing count. + The count is the number of matching records containing this facet value. + + - `alpha`. + Retrieve facet values alphabetically. This setting doesn't influence how facet values are displayed in your UI (see `renderingContent`). For more information, see [facet value display](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/facet-display/js/). @@ -862,16 +814,19 @@ removeWordsIfNoResults: Strategy for removing words from the query when it doesn't return any results. This helps to avoid returning empty search results. -
-
none
-
No words are removed when a query doesn't return results.
-
lastWords
-
Treat the last (then second to last, then third to last) word as optional, until there are results or at most 5 words have been removed.
-
firstWords
-
Treat the first (then second, then third) word as optional, until there are results or at most 5 words have been removed.
-
allOptional
-
Treat all words as optional.
-
+ - `none`. + No words are removed when a query doesn't return results. + + - `lastWords`. + Treat the last (then second to last, then third to last) word as optional, + until there are results or at most 5 words have been removed. + + - `firstWords`. + Treat the first (then second, then third) word as optional, + until there are results or at most 5 words have been removed. + + - `allOptional`. + Treat all words as optional. For more information, see [Remove words to improve results](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/in-depth/why-use-remove-words-if-no-results/). default: none @@ -887,24 +842,18 @@ exactOnSingleWordQuery: description: | Determines how the [Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes) is computed when the search query has only one word. -
-
attribute
-
- The Exact ranking criterion is 1 if the query word and attribute value are the same. - For example, a search for "road" will match the value "road", but not "road trip". -
-
none
-
- The Exact ranking criterion is ignored on single-word searches. -
-
word
-
- The Exact ranking criterion is 1 if the query word is found in the attribute value. - The query word must have at least 3 characters and must not be a stop word. -
-
- - If `exactOnSingleWordQuery` is `word`, only exact matches will be highlighted, partial and prefix matches won't. + - `attribute`. + The Exact ranking criterion is 1 if the query word and attribute value are the same. + For example, a search for "road" will match the value "road", but not "road trip". + + - `none`. + The Exact ranking criterion is ignored on single-word searches. + + - `word`. + The Exact ranking criterion is 1 if the query word is found in the attribute value. + The query word must have at least 3 characters and must not be a stop word. + Only exact matches will be highlighted, + partial and prefix matches won't. default: attribute x-categories: - Query strategy @@ -1076,17 +1025,16 @@ sortRemainingBy: description: | Order of facet values that aren't explicitly positioned with the `order` setting. -
-
count
-
- Order remaining facet values by decreasing count. - The count is the number of matching records containing this facet value. -
-
alpha
-
Sort facet values alphabetically.
-
hidden
-
Don't show facet values that aren't explicitly positioned.
-
. + - `count`. + Order remaining facet values by decreasing count. + The count is the number of matching records containing this facet value. + + - `alpha`. + Sort facet values alphabetically. + + - `hidden`. + Don't show facet values that aren't explicitly positioned. + type: string enum: [count, alpha, hidden] diff --git a/specs/crawler/common/parameters.yml b/specs/crawler/common/parameters.yml index 41b9145eaf..940efb097b 100644 --- a/specs/crawler/common/parameters.yml +++ b/specs/crawler/common/parameters.yml @@ -148,11 +148,6 @@ version: description: Version of the configuration. Version 1 is the initial configuration you used when creating the crawler. minimum: 1 -createdAt: - type: string - description: Timestamp in ISO 8601 format when this version of the configuration was created. - example: 2024-04-02T17:04:30Z - authorId: type: string description: Universally unique identifier (UUID) of the user who created this version of the configuration. diff --git a/specs/crawler/common/schemas/crawlerConfigVersionsResponse.yml b/specs/crawler/common/schemas/crawlerConfigVersionsResponse.yml index d02d5b3810..fd4fe95a74 100644 --- a/specs/crawler/common/schemas/crawlerConfigVersionsResponse.yml +++ b/specs/crawler/common/schemas/crawlerConfigVersionsResponse.yml @@ -11,7 +11,7 @@ allOf: version: $ref: '../parameters.yml#/version' createdAt: - $ref: '../parameters.yml#/createdAt' + $ref: '../../../common/responses/common.yml#/createdAt' authorId: $ref: '../parameters.yml#/authorId' required: diff --git a/specs/crawler/common/schemas/getCrawlerResponse.yml b/specs/crawler/common/schemas/getCrawlerResponse.yml index 3a17325130..745ac30815 100644 --- a/specs/crawler/common/schemas/getCrawlerResponse.yml +++ b/specs/crawler/common/schemas/getCrawlerResponse.yml @@ -11,13 +11,9 @@ BaseResponse: name: $ref: '../parameters.yml#/CrawlerName' createdAt: - type: string - description: Timestamp in ISO 8601 format when the crawler was created. - example: 2024-04-02T12:17:22Z + $ref: '../../../common/responses/common.yml#/createdAt' updatedAt: - type: string - description: Timestamp in ISO 8601 format when the crawler was last updated. - example: 2024-04-02T12:17:22Z + $ref: '../../../common/responses/common.yml#/updatedAt' running: type: boolean description: Whether this crawler is active. @@ -42,14 +38,17 @@ BaseResponse: default: null oneOf: - type: string - description: Timestamp in ISO 8601 format when the last complete reindexing started. + description: Date and time when the last crawl started, in RFC 3339 format. + example: 2024-04-07T09:16:04Z - type: 'null' + description: If null, this crawler hasn't indexed anything yet. lastReindexEndedAt: default: null oneOf: - type: string - description: Timestamp in ISO 8601 format when the last complete reindexing completed. + description: Date and time when the last crawl finished, in RFC 3339 format. - type: 'null' + description: If null, this crawler hasn't indexed anything yet. required: - name - createdAt diff --git a/specs/crawler/paths/crawlerConfigVersion.yml b/specs/crawler/paths/crawlerConfigVersion.yml index 3493c57856..b3cdd7d896 100644 --- a/specs/crawler/paths/crawlerConfigVersion.yml +++ b/specs/crawler/paths/crawlerConfigVersion.yml @@ -23,7 +23,7 @@ get: config: $ref: '../common/schemas/configuration.yml#/Configuration' createdAt: - $ref: '../common/parameters.yml#/createdAt' + $ref: '../../common/responses/common.yml#/createdAt' authorId: $ref: '../common/parameters.yml#/authorId' required: diff --git a/specs/crawler/paths/crawlerTest.yml b/specs/crawler/paths/crawlerTest.yml index d8bd62287f..bdfd1b2917 100644 --- a/specs/crawler/paths/crawlerTest.yml +++ b/specs/crawler/paths/crawlerTest.yml @@ -33,11 +33,11 @@ post: properties: startDate: type: string - description: Timestamp in ISO 8601 format when the test crawl started. + description: Date and time when the test crawl started, in RFC 3339 format. example: 2024-04-02T15:34:29Z endDate: type: string - description: Timestamp in ISO 8601 format when the test crawl ended. + description: Date and time when the test crawl finished, in RFC 3339 format. example: 2024-04-02T15:34:29Z logs: type: array diff --git a/specs/ingestion/common/schemas/destination.yml b/specs/ingestion/common/schemas/destination.yml index 1f6d70fe14..3df3f6ebb5 100644 --- a/specs/ingestion/common/schemas/destination.yml +++ b/specs/ingestion/common/schemas/destination.yml @@ -105,12 +105,11 @@ DestinationType: description: | Destination type. -
-
search
-
Data is stored in an Algolia index.
-
insights
-
Data is recorded as user events in the Insights API.
-
. + - `search`. + Data is stored in an Algolia index. + + - `insights`. + Data is recorded as user events in the Insights API. enum: [search, insights] DestinationIndexPrefix: diff --git a/specs/ingestion/common/schemas/task.yml b/specs/ingestion/common/schemas/task.yml index edd407a09a..8f8ea4f869 100644 --- a/specs/ingestion/common/schemas/task.yml +++ b/specs/ingestion/common/schemas/task.yml @@ -171,36 +171,17 @@ TriggerType: description: | Task trigger, describing when a task should run. -
-
onDemand
-
+ - `onDemand`. + Manually trigger the task with the `/run` endpoint. - Manually trigger the task with the `/run` endpoint. + - `schedule`. + Regularly trigger the task on a `cron` schedule. -
-
schedule
-
+ - `subscription`. + Trigger the task after an event is received, such as, a webhook. - Regularly trigger the task on a `cron` schedule. - -
- -
subscription
- -
- - Trigger the task after an event is received, such as, a webhook. - -
- -
streaming
- -
- - Run the task continuously. - -
-
. + - `streaming`. + Run the task continuously. enum: [onDemand, schedule, subscription, streaming] # schedule trigger diff --git a/specs/ingestion/spec.yml b/specs/ingestion/spec.yml index 891cfa3831..8f81c3d351 100644 --- a/specs/ingestion/spec.yml +++ b/specs/ingestion/spec.yml @@ -7,7 +7,7 @@ info: # Base URLs - The base URLs for making requests to the Ingestion API are: + The base URLs for requests to the Ingestion API are: - `https://data.us.algolia.com` - `https://data.eu.algolia.com` @@ -20,15 +20,9 @@ info: To authenticate your API requests, add these headers: -
-
x-algolia-application-id
-
Your Algolia application ID.
-
x-algolia-api-key
-
- An API key with the necessary permissions to make the request. - The required access control list (ACL) to make a request is listed in each endpoint's reference. -
-
+ - `x-algolia-application-id`. Your Algolia application ID. + - `x-algolia-api-key`. An API key with the necessary permissions to make the request. + The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml index ff1141bae2..c7a4186e0d 100644 --- a/specs/insights/common/schemas/EventAttributes.yml +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -46,7 +46,7 @@ timestamp: type: integer format: int64 description: | - Timestamp of the event in milliseconds in [Unix epoch time](https://wikipedia.org/wiki/Unix_time). + Timestamp of the event, measured in milliseconds since the Unix epoch. By default, the Insights API uses the time it receives an event as its timestamp. example: 1687193127 diff --git a/specs/insights/spec.yml b/specs/insights/spec.yml index b700f96290..dd63f15469 100644 --- a/specs/insights/spec.yml +++ b/specs/insights/spec.yml @@ -25,15 +25,9 @@ info: To authenticate your API requests, add these headers: -
-
x-algolia-application-id
-
Your Algolia application ID.
-
x-algolia-api-key
-
- An API key with the necessary permissions to make the request. - The required access control list (ACL) to make a request is listed in each endpoint's reference. -
-
+ - `x-algolia-application-id`. Your Algolia application ID. + - `x-algolia-api-key`. An API key with the necessary permissions to make the request. + The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). diff --git a/specs/monitoring/common/schemas/Timestamp.yml b/specs/monitoring/common/schemas/Timestamp.yml index 6580f60ea8..97ea99ac66 100644 --- a/specs/monitoring/common/schemas/Timestamp.yml +++ b/specs/monitoring/common/schemas/Timestamp.yml @@ -1,3 +1,3 @@ type: integer format: int64 -description: Timestamp in [Unix epoch time](https://wikipedia.org/wiki/Unix_time) in milliseconds. +description: Timestamp, measured in milliseconds since the Unix epoch. diff --git a/specs/monitoring/spec.yml b/specs/monitoring/spec.yml index e447e4f7c5..64631f47a2 100644 --- a/specs/monitoring/spec.yml +++ b/specs/monitoring/spec.yml @@ -6,7 +6,7 @@ info: # Base URLs - The base URL for making requests to the Monitoring API is: + The base URL for requests to the Monitoring API is: - `https://status.algolia.com` @@ -19,12 +19,8 @@ info: To authenticate requests to the Infrastructure endpoints, add these headers: -
-
x-algolia-application-id
-
Your Algolia application ID.
-
x-algolia-api-key
-
Your Monitoring API key.
-
+ - `x-algolia-application-id`. Your Algolia application ID. + - `x-algolia-api-key`. Your Monitoring API key. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). diff --git a/specs/query-suggestions/paths/getConfigurationStatus.yml b/specs/query-suggestions/paths/getConfigurationStatus.yml index 9679e60a33..1be0a821bc 100644 --- a/specs/query-suggestions/paths/getConfigurationStatus.yml +++ b/specs/query-suggestions/paths/getConfigurationStatus.yml @@ -25,11 +25,11 @@ get: example: false lastBuiltAt: type: string - description: Timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format when the Query Suggestions index was last built. + description: Date and time when the Query Suggestions index was last built, in RFC 3339 format. example: 2023-07-05T08:03:53Z lastSuccessfulBuiltAt: type: string - description: Timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format when the Query Suggestions index was last updated successfully. + description: Date and time when the Query Suggestions index was last updated successfully. example: 2023-07-05T08:03:53Z lastSuccessfulBuildDuration: type: string diff --git a/specs/query-suggestions/paths/getLogFile.yml b/specs/query-suggestions/paths/getLogFile.yml index 03d16061a7..b2592ec999 100644 --- a/specs/query-suggestions/paths/getLogFile.yml +++ b/specs/query-suggestions/paths/getLogFile.yml @@ -19,7 +19,7 @@ get: properties: timestamp: type: string - description: Timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format. + description: Date and time of the log entry, in RFC 3339 format. example: 2023-07-05T08:03:33.898076171Z level: $ref: '../common/enums.yml#/LogLevel' diff --git a/specs/query-suggestions/spec.yml b/specs/query-suggestions/spec.yml index 275dd1da19..659fe97046 100644 --- a/specs/query-suggestions/spec.yml +++ b/specs/query-suggestions/spec.yml @@ -8,7 +8,7 @@ info: # Base URLs - The base URLs for making requests to the Query Suggestions API are: + The base URLs for requests to the Query Suggestions API are: - `https://query-suggestions.us.algolia.com` - `https://query-suggestions.eu.algolia.com` @@ -21,15 +21,9 @@ info: To authenticate your API requests, add these headers: -
-
x-algolia-application-id
-
Your Algolia application ID.
-
x-algolia-api-key
-
- An API key with the necessary permissions to make the request. - The required access control list (ACL) to make a request is listed in each endpoint's reference. -
-
+ - `x-algolia-application-id`. Your Algolia application ID. + - `x-algolia-api-key`. An API key with the necessary permissions to make the request. + The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). diff --git a/specs/search/common/parameters.yml b/specs/search/common/parameters.yml index 6cd63fa10a..aa296b2dcd 100644 --- a/specs/search/common/parameters.yml +++ b/specs/search/common/parameters.yml @@ -10,27 +10,25 @@ HitsPerPage: # headers UserIDInHeader: - name: X-Algolia-User-ID - description: User ID to assign. + name: x-algolia-user-id + description: Unique identifier of the user who makes the search request. in: header required: true schema: - type: string - pattern: '^[a-zA-Z0-9 \-*.]+$' + $ref: '#/userID' # path UserIDInPath: name: userID - description: User ID to assign. + description: Unique identifier of the user who makes the search request. in: path required: true schema: - type: string - pattern: '^[a-zA-Z0-9 \-*.]+$' + $ref: '#/userID' # misc userID: type: string pattern: '^[a-zA-Z0-9 \-*.]+$' - description: User ID. + description: Unique identifier of the user who makes the search request. example: user1 diff --git a/specs/search/helpers/generateSecuredApiKey.yml b/specs/search/helpers/generateSecuredApiKey.yml index d989b33be5..c86c5745c5 100644 --- a/specs/search/helpers/generateSecuredApiKey.yml +++ b/specs/search/helpers/generateSecuredApiKey.yml @@ -6,7 +6,7 @@ method: operationId: generateSecuredApiKey summary: Create secured API keys. description: | - Generates a secured API key without any calls to Algolia's servers. + Generates a secured API key without any requests to Algolia's servers. Secured API keys are API keys that you generate on your server without any API request to Algolia. Secured API keys help in environments where you can't easily update the client-side code, such as mobile apps, @@ -58,7 +58,7 @@ securedAPIKeyRestrictions: validUntil: type: integer format: int64 - description: Timestamp in [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) when the API key should expire. + description: Timestamp when the secured API key expires, measured in seconds since the Unix epoch. restrictIndices: type: array items: diff --git a/specs/search/paths/advanced/getLogs.yml b/specs/search/paths/advanced/getLogs.yml index e502496674..a81bd5cadd 100644 --- a/specs/search/paths/advanced/getLogs.yml +++ b/specs/search/paths/advanced/getLogs.yml @@ -62,7 +62,7 @@ get: properties: timestamp: type: string - description: Timestamp of the API request in ISO 8601 format. + description: Date and time of the API request, in RFC 3339 format. example: 2023-03-08T12:34:56Z method: type: string diff --git a/specs/search/paths/objects/objects.yml b/specs/search/paths/objects/objects.yml index ff778e1a2a..5b92c7c2fb 100644 --- a/specs/search/paths/objects/objects.yml +++ b/specs/search/paths/objects/objects.yml @@ -35,9 +35,7 @@ post: additionalProperties: false properties: createdAt: - type: string - description: Timestamp when the record was added, in ISO 8601 format. - example: 2023-06-29T15:15:40.747Z + $ref: '../../../common/responses/common.yml#/createdAt' taskID: $ref: '../../../common/responses/common.yml#/taskID' objectID: diff --git a/specs/search/spec.yml b/specs/search/spec.yml index fcb75f7dc5..ff428ba0f8 100644 --- a/specs/search/spec.yml +++ b/specs/search/spec.yml @@ -13,7 +13,7 @@ info: # Base URLs - The base URLs for making requests to the Search API are: + The base URLs for requests to the Search API are: - `https://{APPLICATION_ID}.algolia.net` - `https://{APPLICATION_ID}-dsn.algolia.net`. @@ -41,15 +41,9 @@ info: To authenticate your API requests, add these headers: -
-
x-algolia-application-id
-
Your Algolia application ID.
-
x-algolia-api-key
-
- An API key with the necessary permissions to make the request. - The required access control list (ACL) to make a request is listed in each endpoint's reference. -
-
+ - `x-algolia-application-id`. Your Algolia application ID. + - `x-algolia-api-key`. An API key with the necessary permissions to make the request. + The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). diff --git a/specs/usage/common/parameters.yml b/specs/usage/common/parameters.yml index c6a46dd53a..a57cead61c 100644 --- a/specs/usage/common/parameters.yml +++ b/specs/usage/common/parameters.yml @@ -10,7 +10,7 @@ statisticParameter: Use `*` to retrieve all usage metrics, otherwise add one or more of the following metrics, separated by a comma. - ### Search operations + **Search operations** - `search_operations`. All search operations. - `total_search_operations`: Sum of all search operations. @@ -19,7 +19,7 @@ statisticParameter: - `queries_operations`. Number of [single index search](/specs/search#tag/Search/operation/searchSingleIndex) operations. - `multi_queries_operations`. Number of [multi-index search](/specs/search#tag/Search/operation/search) operations. - ### ACL operations + **ACL operations** - `acl_operations`. All ACL operations. - `total_acl_operations`. Sum of all ACL operations. @@ -30,7 +30,7 @@ statisticParameter: - `delete_api_key_operations`. Number of [delete API key](/specs/search#tag/Api-Keys/operation/deleteApiKey) operations. - `list_api_key_operations`. Number of list index API keys operations. - ### Indexing operations + **Indexing operations** - `indexing_operations`. All indexing operations. - `total_indexing_operations`. Sum of all indexing operations. @@ -44,7 +44,7 @@ statisticParameter: - `list_indices_operations`. Number of [list indices](/specs/search#tag/Indices/operation/listIndices) operations. - `wait_task_operations`. Number of [wait](/specs/search#tag/Indices/operation/getTask) operations. - ### Record operations + **Record operations** - `record_operations`. All record operations. - `total_records_operations`. Sum of all record operations. @@ -56,7 +56,7 @@ statisticParameter: - `partial_update_record_operations`. Number of [partially update records](/specs/search#tag/Records/operation/partialUpdateObject) operations. - `update_record_operations`. Number of [add or replace record by objectID](/specs/search#tag/Records/operation/addOrUpdateObject) operations. - ### Synonym operations + **Synonym operations** - `synonym_operations`. All synonym operations. - `total_synonym_operations`. Sum of all synonym operations. @@ -67,7 +67,7 @@ statisticParameter: - `query_synonym_operations`. Number of [search synonyms](/specs/search#tag/Synonyms/operation/searchSynonyms) operations. - `update_synonym_operations`. Number of [save a synonym](/specs/search#tag/Synonyms/operation/saveSynonym) operations. - ### Rule operations + **Rule operations** - `rule_operations`. All rule operations. - `total_rules_operations`. Sum of all rule operations. @@ -78,14 +78,14 @@ statisticParameter: - `save_rules_operations`. Number of [save rule](/specs/search#operation/getIndexUsage) operations. - `search_rules_operations`. Number of [search rules](/specs/search#tag/Rules/operation/searchRules) operations. - ### Total operations + **Total operations** - `total_recommend_requests`. Number of [Recommend requests](https://www.algolia.com/doc/guides/algolia-ai/recommend/) - `total_write_operations`. Number of Write operations - `total_read_operations`. Number of read operations - `total_operations`. Sum of all operations - ### Total Query Suggestions operations + **Total Query Suggestions operations** Query Suggestions operations are a subset of `total_search_operations`. @@ -100,26 +100,26 @@ statisticParameter: - `querysuggestions_total_read_operations`. Number of Query Suggestions Read operations. - `querysuggestions_total_operations`. Sum of all Query Suggestions operations. - ### Processing time + **Processing time** - `avg_processing_time`. Average processing time (in milliseconds). - `90p_processing_time`. 90th percentile of processing time (in milliseconds). - `99p_processing_time`. 99th percentile of processing time (in milliseconds). - `queries_above_last_ms_processing_time`. Number of queries that take one or more seconds to process. - ### Indices + **Indices** - `records`. Number of records. - `data_size`. The size of the records (in bytes). - `file_size`. The size of the records _and_ index metadata (in bytes). - ### Maximum queries per second + **Maximum queries per second** - `max_qps`. [Maximum queries per second](https://support.algolia.com/hc/en-us/articles/4406975224721) per server. - `region_max_qps`. Maximum queries per second per region. - `total_max_qps`. Maximum queries per second across all servers. - ### Used search capacity + **Used search capacity** The following capacities are reported in percent: @@ -130,7 +130,7 @@ statisticParameter: - `total_used_search_capacity`. Maximum search capacity used for all servers. - `total_avg_used_search_capacity`. Average used search capacity for all servers. - ### Degraded queries + **Degraded queries** Check the impact of [degraded queries](https://support.algolia.com/hc/en-us/articles/4406981934481). @@ -138,23 +138,6 @@ statisticParameter: - `degraded_queries_ssd_used_seconds_impacted`. Percentage of seconds affected by `ssd_used` degraded queries. - `degraded_queries_max_capacity_queries_impacted`. Percentage of degraded queries due to all search threads being used. - `degraded_queries_max_capacity_seconds_impacted`. Percentage of seconds affected by `max_capacity` degraded queries. -startDateParameter: - name: startDate - in: query - description: Start date in ISO 8601 format of the time period to analyze. - required: true - schema: - type: string - example: 2024-01-01 - -endDateParameter: - name: endDate - in: query - description: End date in ISO 8601 format of the time period to analyze. - required: true - schema: - type: string - example: 2024-04-04 granularityParameter: name: granularity diff --git a/specs/usage/common/schemas/responses.yml b/specs/usage/common/schemas/responses.yml index f2e63a7679..d37a3edbce 100644 --- a/specs/usage/common/schemas/responses.yml +++ b/specs/usage/common/schemas/responses.yml @@ -12,7 +12,7 @@ Success: properties: t: type: integer - description: Timestamp in milliseconds in Unix epoch time. + description: Timestamp, measured in milliseconds since the Unix epoch. example: 1455451200000 v: description: Value of the statistics. diff --git a/specs/usage/paths/statistic.yml b/specs/usage/paths/statistic.yml index b01170115c..1ad6b14695 100644 --- a/specs/usage/paths/statistic.yml +++ b/specs/usage/paths/statistic.yml @@ -5,8 +5,8 @@ get: Retrieves usage statistics evaluated over a specified period. parameters: - $ref: '../common/parameters.yml#/statisticParameter' - - $ref: '../common/parameters.yml#/startDateParameter' - - $ref: '../common/parameters.yml#/endDateParameter' + - $ref: '../../common/parameters.yml#/StartDateRequired' + - $ref: '../../common/parameters.yml#/EndDateRequired' - $ref: '../common/parameters.yml#/granularityParameter' responses: '200': diff --git a/specs/usage/paths/statisticIndex.yml b/specs/usage/paths/statisticIndex.yml index 36d58f4d88..61096f2f37 100644 --- a/specs/usage/paths/statisticIndex.yml +++ b/specs/usage/paths/statisticIndex.yml @@ -6,8 +6,8 @@ get: parameters: - $ref: '../common/parameters.yml#/statisticParameter' - $ref: '../../common/parameters.yml#/IndexName' - - $ref: '../common/parameters.yml#/startDateParameter' - - $ref: '../common/parameters.yml#/endDateParameter' + - $ref: '../../common/parameters.yml#/StartDateRequired' + - $ref: '../../common/parameters.yml#/EndDateRequired' - $ref: '../common/parameters.yml#/granularityParameter' responses: '200': diff --git a/specs/usage/spec.yml b/specs/usage/spec.yml index bda8d76bb2..f4b8ea68bc 100644 --- a/specs/usage/spec.yml +++ b/specs/usage/spec.yml @@ -16,12 +16,8 @@ info: To authenticate your API requests, add these headers: -
-
x-algolia-application-id
-
Your Algolia application ID.
-
x-algolia-api-key
-
The Usage API key.
-
+ - `x-algolia-application-id`. Your Algolia application ID. + - `x-algolia-api-key`. The Usage API key. You can find your application ID and Usage API key in the [Algolia dashboard](https://dashboard.algolia.com/account). From 10c433c694780d602c183b87c74a2756cc81714f Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Sun, 7 Apr 2024 14:16:40 +0200 Subject: [PATCH 2/3] fix: h2 headings --- specs/analytics/spec.yml | 18 ++++++++---------- specs/crawler/spec.yml | 18 ++++++++---------- specs/ingestion/spec.yml | 10 +++++----- specs/insights/spec.yml | 12 ++++++------ specs/monitoring/spec.yml | 8 ++++---- specs/query-suggestions/spec.yml | 10 +++++----- specs/search/spec.yml | 16 ++++++++-------- specs/usage/spec.yml | 8 ++++---- 8 files changed, 48 insertions(+), 52 deletions(-) diff --git a/specs/analytics/spec.yml b/specs/analytics/spec.yml index 5c1af4f1fb..d0c9a11786 100644 --- a/specs/analytics/spec.yml +++ b/specs/analytics/spec.yml @@ -8,11 +8,7 @@ info: description: | The Analytics API gives you access to metrics related to your Algolia search experience. - # Availability - - Access to this API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing). - - # Base URLs + ## Base URLs The base URLs for requests to the Analytics API are: @@ -23,7 +19,9 @@ info: **All requests must use HTTPS.** - # Authentication + ## Availability and authentication + + Access to the Analytics API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing). To authenticate your API requests, add these headers: @@ -33,18 +31,18 @@ info: You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). - # Rate limits + ## Rate limits You can make up to **100 requests per minute per app** to the Analytics API. The response includes headers with information about the limits. - # Parameters + ## Parameters Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). Non-ASCII characters must be UTF-8 encoded. Plus characters (`+`) are interpreted as spaces. - # Response status and errors + ## Response status and errors The Analytics API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. @@ -52,7 +50,7 @@ info: Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status. Error responses have a `message` property with more information. - # Version + ## Version The current version of the Analytics API is version 2, as indicated by the `/2/` in each endpoint's URL. diff --git a/specs/crawler/spec.yml b/specs/crawler/spec.yml index 57d8a25114..2907930d2e 100644 --- a/specs/crawler/spec.yml +++ b/specs/crawler/spec.yml @@ -4,11 +4,7 @@ info: description: | The Crawler API lets you manage and run your crawlers. - # Availability - - Acess to this API is available with the [Crawler add-on](https://www.algolia.com/pricing/). - - # Base URL + ## Base URL The base URL for making requests to the Crawler API is: @@ -16,7 +12,9 @@ info: **All requests must use HTTPS.** - # Authentication + ## Availability and authentication + + Acess to the Crawler API is available with the [Crawler add-on](https://www.algolia.com/pricing/). To authenticate your API requests, use the **basic authentication** header: @@ -30,11 +28,11 @@ info: You can find both in the [Crawler dashboard](https://crawler.algolia.com/admin/settings/). The Crawler dashboard and API key are different from the regular Algolia dashboard and API keys. - # Request format + ## Request format Request bodies must be JSON objects. - # Parameters + ## Parameters Parameters are passed as query parameters for GET requests, and in the request body for POST and PATCH requests. @@ -42,7 +40,7 @@ info: Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). Non-ASCII characters must be UTF-8 encoded. - # Response status and errors + ## Response status and errors The Crawler API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. @@ -50,7 +48,7 @@ info: Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status. Error responses have a `message` property with more information. - # Version + ## Version The current version of the Crawler API is version 1, as indicated by the `/1/` in each endpoint's URL. version: 1.0.0 diff --git a/specs/ingestion/spec.yml b/specs/ingestion/spec.yml index 8f81c3d351..383a9db98c 100644 --- a/specs/ingestion/spec.yml +++ b/specs/ingestion/spec.yml @@ -5,7 +5,7 @@ info: The Ingestion API lets you connect third-party services and platforms with Algolia and schedule tasks to ingest your data. The Ingestion API powers the no-code [data connectors](https://dashboard.algolia.com/connectors). - # Base URLs + ## Base URLs The base URLs for requests to the Ingestion API are: @@ -16,7 +16,7 @@ info: **All requests must use HTTPS.** - # Authentication + ## Authentication To authenticate your API requests, add these headers: @@ -26,11 +26,11 @@ info: You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). - # Request format + ## Request format Request bodies must be JSON objects. - # Response status and errors + ## Response status and errors Response bodies are JSON objects. Deleting a user token returns an empty response body with rate-limiting information as headers. @@ -43,7 +43,7 @@ info: Check the [Events](https://dashboard.algolia.com/events/health) health section, whether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking. - # Version + ## Version The current version of the Insights API is version 1, as indicated by the `/1/` in each endpoint's URL. diff --git a/specs/insights/spec.yml b/specs/insights/spec.yml index dd63f15469..ad8c07cc9d 100644 --- a/specs/insights/spec.yml +++ b/specs/insights/spec.yml @@ -7,12 +7,12 @@ info: They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. - # Client libraries + ## Client libraries Use Algolia's API clients, libraries, and integrations to collect events from your UI and send them to the Insights API. See: [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/) - # Base URLs + ## Base URLs The base URLs for making requests to the Insights API are: @@ -21,7 +21,7 @@ info: **All requests must use HTTPS.** - # Authentication + ## Authentication To authenticate your API requests, add these headers: @@ -31,11 +31,11 @@ info: You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). - # Request format + ## Request format Request bodies must be JSON objects. - # Response status and errors + ## Response status and errors Response bodies are JSON objects. Deleting a user token returns an empty response body with rate-limiting information as headers. @@ -48,7 +48,7 @@ info: Check the [Events](https://dashboard.algolia.com/events/health) health section, whether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking. - # Version + ## Version The current version of the Insights API is version 1, as indicated by the `/1/` in each endpoint's URL. version: 1.0.0 diff --git a/specs/monitoring/spec.yml b/specs/monitoring/spec.yml index 64631f47a2..c992fabe42 100644 --- a/specs/monitoring/spec.yml +++ b/specs/monitoring/spec.yml @@ -4,7 +4,7 @@ info: description: | The Monitoring API lets you check the status of your Algolia infrastructure. - # Base URLs + ## Base URLs The base URL for requests to the Monitoring API is: @@ -12,7 +12,7 @@ info: **All requests must use HTTPS.** - # Availability and authentication + ## Availability and authentication Access to the [Infrastructure](#tag/infrastructure) endpoints is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing). @@ -26,7 +26,7 @@ info: Other endpoints don't require authentication. - # Response status and errors + ## Response status and errors The Monitoring API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. @@ -34,7 +34,7 @@ info: Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status. Error responses have a `message` property with more information. - # Version + ## Version The current version of the Monitoring API is version 1, as indicated by the `/1/` in each endpoint's URL. version: 1.0.0 diff --git a/specs/query-suggestions/spec.yml b/specs/query-suggestions/spec.yml index 659fe97046..ab2a653ea5 100644 --- a/specs/query-suggestions/spec.yml +++ b/specs/query-suggestions/spec.yml @@ -6,7 +6,7 @@ info: Query Suggestions add new indices to your Algolia application with popular search queries, external suggestions, or facet values. In your user interface, you can query the Query Suggestions indices like regular indices and add [suggested searches](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js/) to guide users and speed up their search. - # Base URLs + ## Base URLs The base URLs for requests to the Query Suggestions API are: @@ -17,7 +17,7 @@ info: **All requests must use HTTPS.** - # Authentication + ## Authentication To authenticate your API requests, add these headers: @@ -27,11 +27,11 @@ info: You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). - # Request format + ## Request format Request bodies must be JSON objects. - # Response status and errors + ## Response status and errors Response bodies are JSON objects. Deleting a user token returns an empty response body with rate-limiting information as headers. @@ -39,7 +39,7 @@ info: Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status. Error responses have a `message` property with more information. - # Version + ## Version The current version of the Query Suggestions API is version 1, as indicated by the `/1/` in each endpoint's URL. version: 1.0.0 diff --git a/specs/search/spec.yml b/specs/search/spec.yml index ff428ba0f8..589d3e8b5c 100644 --- a/specs/search/spec.yml +++ b/specs/search/spec.yml @@ -4,14 +4,14 @@ info: description: | The Algolia Search API lets you search, configure, and mange your indices and records. - # Client libraries + ## Client libraries Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps. The official API clients are covered by Algolia's [Service Level Agreement](https://www.algolia.com/policies/sla/). See: [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/) - # Base URLs + ## Base URLs The base URLs for requests to the Search API are: @@ -24,7 +24,7 @@ info: **All requests must use HTTPS.** - # Retry strategy + ## Retry strategy To guarantee a high availability, implement a retry strategy for all API requests using the URLs of your servers as fallbacks: @@ -37,7 +37,7 @@ info: All Algolia API clients implement this retry strategy. - # Authentication + ## Authentication To authenticate your API requests, add these headers: @@ -47,11 +47,11 @@ info: You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account). - # Request format + ## Request format Depending on the endpoint, request bodies are either JSON objects or arrays of JSON objects, - # Parameters + ## Parameters Parameters are passed as query parameters for GET and DELETE requests, and in the request body for POST and PUT requests. @@ -64,7 +64,7 @@ info: - A comma-separated string: `attributesToRetrieve=title,description` - A URL-encoded JSON array: `attributesToRetrieve=%5B%22title%22,%22description%22%D` - # Response status and errors + ## Response status and errors The Search API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. @@ -72,7 +72,7 @@ info: Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status. Error responses have a `message` property with more information. - # Version + ## Version The current version of the Search API is version 1, as indicated by the `/1/` in each endpoint's URL. version: 1.0.0 diff --git a/specs/usage/spec.yml b/specs/usage/spec.yml index f4b8ea68bc..6289c87f84 100644 --- a/specs/usage/spec.yml +++ b/specs/usage/spec.yml @@ -4,7 +4,7 @@ info: description: | The Usage API gives you access to statistics about all requests made to your Algolia applications. - # Base URL + ## Base URL The base URL for requests to the Usage API is: @@ -12,7 +12,7 @@ info: **All requests must use HTTPS.** - # Authentication + ## Authentication To authenticate your API requests, add these headers: @@ -21,7 +21,7 @@ info: You can find your application ID and Usage API key in the [Algolia dashboard](https://dashboard.algolia.com/account). - # Response status and errors + ## Response status and errors The Usage API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. @@ -29,7 +29,7 @@ info: Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status. Error responses have a `message` property with more information. - # Version + ## Version The current version of the Usage API is version 1, as indicated by the `/1/` in each endpoint's URL. version: 1.0.0 From f92a2f10b5d0b840372ae5efc0c3bd48da6e664d Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Sun, 7 Apr 2024 15:49:04 +0200 Subject: [PATCH 3/3] fix: spelling somehow needed --- specs/search/common/parameters.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/search/common/parameters.yml b/specs/search/common/parameters.yml index aa296b2dcd..5b22aeaf1c 100644 --- a/specs/search/common/parameters.yml +++ b/specs/search/common/parameters.yml @@ -10,7 +10,7 @@ HitsPerPage: # headers UserIDInHeader: - name: x-algolia-user-id + name: X-Algolia-User-ID description: Unique identifier of the user who makes the search request. in: header required: true