api-integration_skill

Overview

This skill provides practical best practices for designing and implementing integrations with Kuroco Headless CMS APIs. It covers endpoint structure, authentication methods (Cookie, JWT, StaticToken), CORS, caching, rate limiting, pagination, and error handling. Use it to standardize API calls, secure access, and handle common runtime errors.

How this skill works

The skill explains how Kuroco API paths are organized and what settings each endpoint requires (model, operation, cache, rate limits, auth). It describes three authentication patterns (session cookie for web, JWT token for mobile, StaticToken for server-to-server) and shows concrete request patterns using fetch/axios. It also inspects response headers for cache and rate-limit info, and outlines robust error handling strategies for 400/401/403/404/429/500 scenarios.

When to use it

• Designing new Kuroco API endpoints or reviewing existing ones
• Implementing authentication or token flows for web, mobile, or backend
• Configuring CORS, cache headers, and rate limits for production
• Building client SDKs or API wrappers with pagination and filters
• Troubleshooting 401/403/429 errors and optimizing retry behavior

Best practices

• Use cookie-based auth (credentials: 'include') for same-domain web apps to leverage session handling.
• Use JWT (X-RCMS-API-ACCESS-TOKEN) for mobile clients; store access and refresh tokens securely and refresh before expiry.
• Use StaticToken for server-to-server calls and set it in API security settings in the admin console.
• Set cache durations based on content: static = 86400s, low-update = 604800s, auth-required = 0s.
• Honor rate-limit headers (x-rcms-ratelimit-*) and implement exponential backoff on 429 responses.
• Return clear error messages and map HTTP codes to actions: 401 -> re-authenticate, 403 -> check permissions.

Example use cases

• Implement a news listing with pageID/cnt pagination and pageInfo parsing on the client.
• Build a login flow: POST /login (cookie) or /token (JWT), then store grant or access/refresh tokens.
• Create content via POST to /news/insert using credentials: 'include' for session-based requests.
• Protect internal APIs using StaticToken and restrict CORS to allowed origins for frontend domains.
• Handle 429 responses by reading x-rcms-ratelimit-reset and retrying after the specified delay.