Public API

How to add new api routes

Implementation

• Wrap with withMiddleware

• Type-safe and authed API Route with createAuthedAPIRoute

• Add zod types to /features/public-api/types folder.

  • Use coerce to handle primitives, such as dates, for use in your application and tests.
  • Use strict() on all objects that should not return additional properties. Recommended as default. In these cases, the test utility makeZodVerifiedAPICall will throw an error if the response contains additional properties. Also, we will log an error in production if the response contains additional properties.

• Throw errors defined in shared/src/errors which translate to HTTP status codes

Testing

• Add tests for all standard cases
• use makeZodVerifiedAPICall to test the API response against the zod response schema

API Reference

• Add to fern including docs attributes
• Build with fern generate --api server and fern generate --api client, then commit the changes to the API reference

SDKs

• Copy/paste fern-generated types or api reference to Python and JS SDKs respectively
• Implement wrapping functions if needed

How to refactor existing apis to this pattern

1. Move request types to features/public-api/types
2. Create response types in features/public-api/types
3. Validate response type with validateZodSchema in the API route to get type warnings in case of mismatch
4. Refactor api route by passing current api route to LLM together with example of e.g. public/v2/datasets.ts