feat: add JSON:API content negotiation support for REST endpoints

[teethaking]

---

Summary

Adds support for Accept: application/vnd.api+json content negotiation, allowing clients to request JSON:API-shaped responses from major endpoints — the convention preferred by enterprise integrators — without changing the default response shape for existing consumers.

Closes #135

---

What changed

src/middleware/jsonapi.ts (new)

• Middleware that inspects the incoming Accept header
• When Accept: application/vnd.api+json is present, transforms the standard response payload into a JSON:API-compliant document:
  • Wraps resources in the data envelope with type, id, and attributes
  • Maps relationships (where applicable) into the relationships key per the JSON:API spec
  • Sets the response Content-Type to application/vnd.api+json
• When the header is absent or set to a standard type (e.g. application/json), the existing response shape is returned unchanged — fully backward compatible
• Applied to three major endpoints (wired in their respective route handlers) to demonstrate and validate the pattern

Documentation

• Documented the supported Accept header and resulting response shape
• Listed the three endpoints that currently support JSON:API negotiation
• Included example request/response pairs showing the default JSON shape vs the JSON:API-negotiated shape

---

How to verify

• Send a request to each of the three supported endpoints with Accept: application/vnd.api+json and assert the response is JSON:API-shaped (data, type, id, attributes)
• Send the same requests with no Accept header (or application/json) and assert the original response shape is unchanged
• Confirm Content-Type: application/vnd.api+json is set on negotiated responses
• Review documentation for accuracy against actual endpoint behavior

---

Checklist

• src/middleware/jsonapi.ts implements content negotiation based on Accept header
• Three endpoints support JSON:API-shaped responses
• Default (non-JSON:API) response shape unchanged for existing consumers
• Response Content-Type correctly set when JSON:API is negotiated
• Documentation describes supported endpoints, header, and response shape with examples
• Closes JSON:API content negotiation #135

[drips-wave]

@teethaking Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits