Context
We built a Harper app with a single custom resource class handling ~30 API routes plus static file serving. The custom-resources rule explains how to create a resource class and map HTTP methods, but doesn't cover the routing and response mechanics we needed to figure out.
Caveat: Our patterns may be unconventional — we used a single resource with manual path routing rather than multiple resource classes. If Harper has a better idiomatic approach, the skill should show it.
1. target parameter and sub-path routing
What we hit: We needed to handle routes like /myapp/api/users, /myapp/api/reports, etc. Harper doesn't pass the full URL to the resource — it passes the sub-path after the resource prefix via a target parameter.
What we did: Wrote a helper to extract the path from target and used a series of if (path === "/api/users") conditionals. We couldn't find documentation on how target works, what properties it has, or whether Harper supports dynamic path segments (like /api/users/:id).
What the skill should do: Document what target is, what properties it exposes, and how to extract the request path. If Harper supports pattern-based routing or dynamic segments, show how. If the intended pattern is multiple resource classes (one per route), say that explicitly.
2. Returning custom status codes and headers
What we hit: We needed to return JSON responses with specific status codes (200, 403, 404, 409), set Content-Type headers, and set Set-Cookie headers for auth. The resource method signature and return type aren't documented.
What we did: Through experimentation, we found that returning a Response object works. We wrote jsonResponse(), htmlResponse(), and redirect() helpers. But we're not confident this is the intended pattern.
What the skill should do: Show how to return responses with custom status codes, headers (especially Set-Cookie as an array — comma-separated strings don't work), and different content types (JSON, HTML, binary).
3. Error handling in resources
What we hit: When our resource threw an unhandled exception, Harper returned a generic error that sometimes leaked internal details (stack traces, file paths). We weren't sure what the default error behavior was or how to control it.
What we did: Wrapped all route handlers in try/catch and returned sanitized error responses.
What the skill should do: Document what happens when a resource method throws (what status code? what body?), and show the recommended pattern for error handling. Even a simple "always catch errors and return a structured response" example would help.
4. Interaction between custom resources and static file serving
What we hit: Our resource class serves both API routes AND static files (HTML, CSS, JS) from the same URL prefix. We needed to understand the precedence: does static.files in config.yaml take priority, or does the custom resource?
What we did: Handled static file serving manually in our resource's GET handler, reading files from disk and setting appropriate content types. We're not sure if this was necessary or if we could have let Harper's static serving handle it.
What the skill should do: Clarify how custom resources and static.files interact on the same URL space. If they can coexist, explain the precedence rules.
Context
We built a Harper app with a single custom resource class handling ~30 API routes plus static file serving. The
custom-resourcesrule explains how to create a resource class and map HTTP methods, but doesn't cover the routing and response mechanics we needed to figure out.Caveat: Our patterns may be unconventional — we used a single resource with manual path routing rather than multiple resource classes. If Harper has a better idiomatic approach, the skill should show it.
1.
targetparameter and sub-path routingWhat we hit: We needed to handle routes like
/myapp/api/users,/myapp/api/reports, etc. Harper doesn't pass the full URL to the resource — it passes the sub-path after the resource prefix via atargetparameter.What we did: Wrote a helper to extract the path from
targetand used a series ofif (path === "/api/users")conditionals. We couldn't find documentation on howtargetworks, what properties it has, or whether Harper supports dynamic path segments (like/api/users/:id).What the skill should do: Document what
targetis, what properties it exposes, and how to extract the request path. If Harper supports pattern-based routing or dynamic segments, show how. If the intended pattern is multiple resource classes (one per route), say that explicitly.2. Returning custom status codes and headers
What we hit: We needed to return JSON responses with specific status codes (200, 403, 404, 409), set
Content-Typeheaders, and setSet-Cookieheaders for auth. The resource method signature and return type aren't documented.What we did: Through experimentation, we found that returning a
Responseobject works. We wrotejsonResponse(),htmlResponse(), andredirect()helpers. But we're not confident this is the intended pattern.What the skill should do: Show how to return responses with custom status codes, headers (especially
Set-Cookieas an array — comma-separated strings don't work), and different content types (JSON, HTML, binary).3. Error handling in resources
What we hit: When our resource threw an unhandled exception, Harper returned a generic error that sometimes leaked internal details (stack traces, file paths). We weren't sure what the default error behavior was or how to control it.
What we did: Wrapped all route handlers in try/catch and returned sanitized error responses.
What the skill should do: Document what happens when a resource method throws (what status code? what body?), and show the recommended pattern for error handling. Even a simple "always catch errors and return a structured response" example would help.
4. Interaction between custom resources and static file serving
What we hit: Our resource class serves both API routes AND static files (HTML, CSS, JS) from the same URL prefix. We needed to understand the precedence: does
static.filesin config.yaml take priority, or does the custom resource?What we did: Handled static file serving manually in our resource's GET handler, reading files from disk and setting appropriate content types. We're not sure if this was necessary or if we could have let Harper's static serving handle it.
What the skill should do: Clarify how custom resources and
static.filesinteract on the same URL space. If they can coexist, explain the precedence rules.