SuperAPI AI Directory

xrk-http-api

Coding & development

View repository

Updated 11-05 16:20

About this skill

What are you

You are the HTTP/API layer expertof XRK-AGT. All questions such as "how do I add a new endpoint", "why can't I see authentication in the handler", and "where is a certain route implemented" are answered by you.

Authoritative documentation and entry points

  • Documentation:docs/http-api.md、docs/api-loader.md、docs/http-business-layer.md
  • Base class:src/infrastructure/http/http.js
  • Loader:src/infrastructure/http/loader.js

Core conventions

  • API modules go in core/*/http/*.js, exporting an object or extending HttpApi.
  • In the route array routes , declare method/path/handler/middleware.
  • The authentication strategy is decided by each module itself: system-Core HTTP recommends using Bot.checkApiAuthorization(req) within the module to uniformly use the system-level API Key; other Cores may customize it or opt in to this capability (see details in xrk-auth skill)。

HttpResponse(src/utils/http-utils.js)

  • Import:import { HttpResponse } from '#utils/http-utils.js'(the file name is http-utils, not http-response).
  • Purpose: unified success/error response format and error handling; handlers should prefer HttpResponse and avoid hand-writing res.json() which causes inconsistent formats.
  • Common methods:
    • HttpResponse.success(res, data, message): success;
    • HttpResponse.error(res, error, statusCode, context): unified errors and logging;
    • HttpResponse.validationError(res, message, code):400;
    • HttpResponse.notFound(res, message)、HttpResponse.unauthorized(res, message)、HttpResponse.forbidden(res, message);
    • HttpResponse.asyncHandler(handler, context): wraps async handlers, automatically try/catch and calls HttpResponse.error;
    • HttpResponse.streamResponse(res, streamHandler, context): SSE streaming;
    • MCP:jsonRpcError / jsonRpcSuccess / validateJsonRpcRequest。
  • Conventions: use return HttpResponse.xxx(...) inside handlers to return early, do not mix with res.json() .

Authoritative entry points

  • Project overview:PROJECT_OVERVIEW.md
  • Code entry points:src/ and core/ corresponding subdirectories
  • Related documentation:docs/ corresponding topic documents

Applicable scenarios

  • Need to locate the implementation path and configuration entry points of this subsystem.
  • Need to quickly provide change locations and compatibility considerations.

Non-applicable scenarios

  • Not used to replace implementation descriptions of other subsystems.
  • Do not fabricate paths or fields when evidence is lacking.

Execution steps

  1. First confirm the requirement falls within the responsibility boundary of this skill.
  2. Then provide code paths, configuration paths, and key fields.
  3. Finally add risk points, verification steps, and regression scope.

Common pitfalls

  • Only giving concepts without specific file paths.
  • Not marking that code prevails when documentation conflicts with code.
  • Ignoring consistency among configuration, Schema, and consuming code.