feat: update API check overview page #1230
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
| Start as you mean to go on. Pick a sensible name, something that other members of your team are going to understand. A meaningful name will not only help you and others identify your checks within Checkly, but it will help provide better a better alerting experience if your checks fall into an alert state. | ||
| Tags can relate your checks together, they also determine which checks are shown on your public [dashboards](/docs/dashboards/). | ||
|  | ||
| You can use these checks to verify that: |
There was a problem hiding this comment.
@guolau let's make clear that these are examples (i.e. more can be done than what is listed here)
| * Your endpoint is properly authenticating requests. | ||
|
|
||
| **2. The HTTP request** | ||
| If your endpoint is unresponsive or fails assertions, the check will trigger any configured alerts. |
There was a problem hiding this comment.
@guolau considering this is an overview page, let's link back to the alerting overview page to help our first time users.
|
|
||
| Our [time limits](limits) are customisable, sometimes API's can be slow, but not broken. We call that **degraded**. We let you specify when an API check should be marked as **degraded** and when it should be marked as **failed**. | ||
|  | ||
| Sometimes APIs can be slow, but not broken. We call this **degraded**. You can set [response time limits](/docs/api-checks/limits/) to specify when an API check should be marked as **degraded** and when it should be marked as **failed**. |
There was a problem hiding this comment.
@guolau we're only using bold text in this section. Can we either stick to plain text or highlight this differently, maybe with ``?
There was a problem hiding this comment.
@guolau let's use a screenshot where "Run request" is not greyed out
|  | ||
| The above example defines: | ||
| - The basic check properties like `name`, `activated` etc. | ||
| - The HTTP method `GET` the `url`. |
There was a problem hiding this comment.
@guolau this is phrased weirdly. Perhaps "The HTTP method GET and the target url of the request?
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
WalkthroughThe update revises the API checks documentation. The document title changed from “Monitoring APIs with Checks” to “Getting started with API checks.” The introduction and section headings were reformatted and reorganized, with content rewritten for clarity. New sections such as "Retries & alerting," "Testing," and a "CLI example" have been added, including a corresponding TypeScript code snippet that illustrates API check configuration using Checkly constructs. Changes
Suggested reviewers
Tip ⚡🧪 Multi-step agentic review comment chat (experimental)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
site/content/docs/api-checks/_index.md (5)
46-48: Setup and Teardown Scripts DescriptionThe explanation is detailed and informative. Consider hyphenating "last minute processing" to "last-minute processing" since it acts as a compound adjective modifying "processing":
-Setup scripts allow you to do last minute processing of test data and request options. +Setup scripts allow you to do last-minute processing of test data and request options.🧰 Tools
🪛 LanguageTool
[uncategorized] ~48-~48: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... scripts Setup scripts allow you to do last minute processing of test data and request opt...(EN_COMPOUND_ADJECTIVE_INTERNAL)
56-63: Assertions List FormattingThe unordered list under the Assertions section currently uses dashes. To conform with our markdown style guidelines, please change them to asterisks:
- - The HTTP status code returned from the API - - Something missing or required within the response body - - A specific response header - - A specific response time + * The HTTP status code returned from the API + * Something missing or required within the response body + * A specific response header + * A specific response time🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
60-60: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
61-61: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
62-62: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
63-63: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
67-69: Scheduling & Locations FormattingThe Scheduling & Locations section provides key information; however, the sentence on line 69 could be clearer. Consider adding a comma before "and" for improved readability:
-If you don't select more than one location and you've disabled retrying checks from the same location, we will pick a random location when retrying checks. +If you don't select more than one location, and you've disabled retrying checks from the same location, we will pick a random location when retrying checks.🧰 Tools
🪛 LanguageTool
[uncategorized] ~69-~69: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ... you don't select more than one location and you've disabled retrying checks from th...(COMMA_COMPOUND_SENTENCE)
106-109: CLI Example List StyleThe list explaining what the CLI example defines is currently using dashes. Please update these to asterisks to maintain consistent markdown list styling:
- - The basic check properties like `name`, `activated` etc. - - The `GET` HTTP method and target `url` of the request. - - An array of assertions to assert the HTTP response status is correct. + * The basic check properties like `name`, `activated` etc. + * The `GET` HTTP method and target `url` of the request. + * An array of assertions to assert the HTTP response status is correct.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
107-107: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
108-108: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
109-109: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
113-119: Next Steps Section RefinementThe “Next steps” section is very useful; however, on line 116, the term "commonly-used" would read better as "commonly used" without the hyphen:
-* Store commonly-used or sensitive data, like usernames and auth tokens, in [environment variables and secrets](/docs/api-checks/variables/). +* Store commonly used or sensitive data, like usernames and auth tokens, in [environment variables and secrets](/docs/api-checks/variables/).🧰 Tools
🪛 LanguageTool
[uncategorized] ~116-~116: The hyphen in commonly-used is redundant.
Context: ...](/guides/monitoring-as-code/). * Store commonly-used or sensitive data, like usernames and a...(ADVERB_LY_HYPHEN_FIX)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (10)
site/assets/docs/images/api-checks/overview-alerting.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-assertions.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-check-overview.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-create-check.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-http.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-locations.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-name-tag.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-response-time.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-schedule.pngis excluded by!**/*.pngsite/assets/docs/images/api-checks/overview-scripts.pngis excluded by!**/*.png
📒 Files selected for processing (1)
site/content/docs/api-checks/_index.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
site/content/docs/api-checks/_index.md
[uncategorized] ~48-~48: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... scripts Setup scripts allow you to do last minute processing of test data and request opt...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[uncategorized] ~69-~69: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ... you don't select more than one location and you've disabled retrying checks from th...
(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~116-~116: The hyphen in commonly-used is redundant.
Context: ...](/guides/monitoring-as-code/). * Store commonly-used or sensitive data, like usernames and a...
(ADVERB_LY_HYPHEN_FIX)
🪛 markdownlint-cli2 (0.17.2)
site/content/docs/api-checks/_index.md
60-60: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
61-61: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
62-62: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
63-63: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
107-107: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
108-108: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
109-109: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
🔇 Additional comments (13)
site/content/docs/api-checks/_index.md (13)
2-3: Title and Display Title UpdateThe title and display title have been updated to clearly reflect the page’s new focus on getting started with API checks. Please ensure these values are consistently referenced elsewhere in the documentation.
16-16: Improved IntroductionThe introductory sentence now effectively explains that API checks work by sending HTTP requests to verify response speed and correctness. This enhancement improves clarity for first-time users.
18-18: Updated Screenshot ReferenceThe updated image reference should help users visualize the API check overview page. Verify that the image exists at the provided path and reflects the current UI.
20-23: Clear API Check ExamplesThe bullet list clearly outlines concrete examples (e.g., verifying a 200 status code, JSON schema, proper authentication). This upgrade improves understandability.
27-27: New ‘Creating an API check’ SectionThe addition of the "Creating an API check" header provides a clear entry point for users, guiding them where to begin when setting up their own checks.
29-29: Updated Create-Check ScreenshotThe screenshot for creating an API check now reflects the latest UI. Please confirm that the image accurately represents the current creation process.
31-35: Enhanced 'Name and Tags' SectionThe revised explanation emphasizes the importance of meaningful naming and tagging, which will help in both identification and alerting.
38-42: HTTP Request Section ClarityThe HTTP request section now clearly explains the configuration options—such as body data, headers, and query parameters—which is valuable for users setting up custom API checks.
52-54: Response Time Limits ExplanationThe description in this section clearly communicates the concept of degraded performance versus outright failure, which will help users set realistic performance thresholds.
73-77: Retries & Alerting SectionThe updated section on retry strategies and alerting channels is concise and informative. Users will benefit from the clearer guidance on notification options.
79-81: Testing Section EnhancementThe Testing section now clearly communicates that checks can be run as E2E tests either locally or through CI/CD pipelines, which is very useful for deployment validation.
83-87: CLI Example IntroductionThis section now provides a succinct introduction to the CLI example, combining contextual information with a clear call to action for developers to try it out.
89-104: CLI Code Example QualityThe TypeScript code snippet is well-formatted and demonstrates how to define an API check with Checkly constructs (including the use of assertions). This is a strong addition for users who prefer a code-centric approach.
Affected Components
Pre-Requisites
npm run lint)Notes for the Reviewer
Updated the API check overview page according to the check overview page facelift proposal.
Summary of changes: