diff --git a/docs/guides/fundamentals/_category_.json b/docs/guides/fundamentals/_category_.json new file mode 100644 index 00000000..5506d753 --- /dev/null +++ b/docs/guides/fundamentals/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Fundamentals", + "position": 2, + "link": { + "type": "generated-index", + "description": "Core technical details about how the Anytype API works." + } +} diff --git a/docs/guides/fundamentals/rate-limits.md b/docs/guides/fundamentals/rate-limits.md new file mode 100644 index 00000000..08a2dbd3 --- /dev/null +++ b/docs/guides/fundamentals/rate-limits.md @@ -0,0 +1,42 @@ +--- +sidebar_position: 1 +title: "Rate Limits" +description: "Understanding rate limits and how to handle them when using the Anytype API." +keywords: [anytype, api, rate limits, throttling, best practices] +--- + +# Rate Limits + +The Anytype API implements rate limiting as a guardrail to protect your local Anytype instance from being overwhelmed by too many requests. Since the API runs on your own resources, these limits help ensure stable operation. + +## Rate Limit Configuration + +The API uses **burst rate limiting**: + +| Parameter | Value | +|-----------|-------| +| Sustained rate | 1 request per second | +| Burst size | 60 requests | + +This means you can send up to 60 requests in quick succession (burst), after which requests are limited to 1 per second until the burst capacity recovers. + +## Disabling Rate Limits + +You can disable rate limiting by setting the following environment variable before starting Anytype: + +```bash +ANYTYPE_API_DISABLE_RATE_LIMIT=1 +``` + +## Rate Limit Errors + +When you exceed the rate limit, the API returns a `429` status code with the following response: + +```json +{ + "code": "rate_limit_exceeded", + "message": "Rate limit exceeded", + "object": "error", + "status": 429 +} +``` diff --git a/docs/guides/fundamentals/status-codes.md b/docs/guides/fundamentals/status-codes.md new file mode 100644 index 00000000..22b887b8 --- /dev/null +++ b/docs/guides/fundamentals/status-codes.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 2 +title: "Status Codes" +description: "HTTP status codes returned by the Anytype API." +keywords: [anytype, api, status codes, errors, http] +--- + +# Status Codes + +The Anytype API uses standard HTTP status codes to indicate the success or failure of requests. + +## Success Codes + +| HTTP Status | Description | +|:------------|:------------| +| 200 | The request was successful. | +| 201 | A new resource was created. | + +## Error Codes + +Error responses include a JSON body with additional details: + +```json +{ + "code": "error_code", + "message": "Human-readable error message", + "object": "error", + "status": 400 +} +``` + +| HTTP Status | `code` | Description | +|:------------|:-------|:------------| +| 400 | `bad_request` | The request body is invalid or malformed. | +| 401 | `unauthorized` | The API key is missing or invalid. | +| 403 | `forbidden` | The API key doesn't have permission for this operation. | +| 404 | `object_not_found` | The requested resource does not exist. | +| 410 | `resource_gone` | The resource has been deleted. | +| 429 | `rate_limit_exceeded` | Too many requests. See [Rate Limits](./rate-limits.md). | +| 500 | `internal_server_error` | An unexpected error occurred. | diff --git a/docs/guides/sidebar.ts b/docs/guides/sidebar.ts index c4479055..94f13330 100644 --- a/docs/guides/sidebar.ts +++ b/docs/guides/sidebar.ts @@ -9,6 +9,13 @@ const sidebar: SidebarsConfig = { description: "The basic concepts you need to get started.", items: [{ type: "autogenerated", dirName: "guides/get-started" }], }, + { + type: "category", + label: "Fundamentals", + collapsed: false, + description: "Core technical details about how the Anytype API works.", + items: [{ type: "autogenerated", dirName: "guides/fundamentals" }], + }, ], }; diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 0ee11430..0adee175 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -3,6 +3,7 @@ import type * as Preset from "@docusaurus/preset-classic"; import type { Config } from "@docusaurus/types"; +import { themes as prismThemes } from "prism-react-renderer"; import { getOpenApiPluginConfig } from "./openapi.config"; import { openApiConfig } from "./openapi.config"; @@ -276,7 +277,16 @@ const config: Config = { `, }, prism: { + theme: prismThemes.github, + darkTheme: prismThemes.vsDark, additionalLanguages: ["ruby", "csharp", "php", "java", "powershell", "json", "bash", "dart", "objectivec", "r"], + magicComments: [ + { + className: "theme-code-block-highlighted-line", + line: "highlight-next-line", + block: { start: "highlight-start", end: "highlight-end" }, + }, + ], }, languageTabs: [ { diff --git a/src/css/custom.css b/src/css/custom.css index 13570f95..fdaf7cf9 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -200,3 +200,51 @@ h4 { transparent 100% ); } + +/* Tables */ +table { + display: table; + width: 100%; + border-collapse: separate; + border-spacing: 0; + border: 1px solid var(--ifm-color-emphasis-200); + border-radius: var(--radius-md); + margin: var(--spacing-xl) 0; + font-size: var(--font-size-small); + overflow: hidden; +} + +table th, +table td { + border: none; + padding: var(--spacing-sm) var(--spacing-md); +} + +table thead th { + background: transparent; + border-bottom: 1px solid var(--ifm-color-emphasis-200); + font-weight: 600; + text-align: left; +} + +table tbody td { + border-bottom: 1px solid var(--ifm-color-emphasis-200); + vertical-align: top; +} + +table tbody tr:last-child td { + border-bottom: none; +} + +table code { + font-size: var(--font-size-caption); +} + +[data-theme="dark"] table { + border-color: var(--ifm-color-emphasis-300); +} + +[data-theme="dark"] table thead th, +[data-theme="dark"] table tbody td { + border-color: var(--ifm-color-emphasis-300); +}