OpenAPIs using remote functions

[ixxie]

Describe the problem

Remote functions are a blast to work with in SvelteKit. But of course, there is a whole world out there beyond SvelteKit. So often one would want to expose a REST API. OpenAPI is a well established standard, not only providing automated documentation solutions, but also automated SDK generation in many languages.

Describe the proposed solution

Since remote functions already compile to endpoints, I wondered if it may be feasible to support generating REST APIs like this:

// src/openapi.server.ts
import { 
  createFooCommand,
  readFooQuery,
  updateFooCommand,
  deleteFooCommand
} from '$lib/remotes/foo.remote.ts';
import { 
  createBarCommand,
  readBarQuery,
  updateBarCommand,
  deleteBarCommand
} from '$lib/remotes/bar.remote.ts';

export const spec = {
  foo: {
    POST: createFooCommand
       .endpoint({
           // additional options passed here
       }),
    GET: readFooCommand,
    PUT: updateFooCommand
    DELETE: deleteFooCommand
  },
  bar: {
     // etc
  }
}

Alternatives considered

Currently, as far as I know, one can either:

1. Manually write endpoint wrappers for remote functions and somehow generate and serve an openapi.json file
2. Use a fallback method handler to dynamically generate the full API and serve the openapi.json

Importance

would make my life easier

Additional Information

I'm not exactly sure how this sort of proposal plays with guards such as proposed here: #14612

[elliott-with-the-longest-name-on-github]

I'm not sure what the overall solution to this looks like. I definitely think OpenAPI support and "I want to expose this remote function as an endpoint for other apps" are things we're going to look into.

For now, I would recommend creating your own simple wrapper function that you can export as an endpoint:

// /**/+server.ts
import { asEndpoint } from '$lib';
import { readFooCommand } from '$lib/remotes/remote.foo.ts';

export const GET = asEndpoint(readFooCommand);

If you wanted to write your own more-comprehensive version (and potentially publish it as an NPM package), you could imagine an API like this:

// /$lib/remote-endpoints.ts

import { 
  createFooCommand,
  readFooQuery,
  updateFooCommand,
  deleteFooCommand
} from '$lib/remotes/foo.remote.ts';

export const config = createRemoteAPI({
  foo: {
    POST: createFooCommand,
    GET: readFooCommand,
    PUT: updateFooCommand
    DELETE: deleteFooCommand
  },
  bar: {
     // etc
  }
})

// /openapi.json/+server.ts
import { config } from '$lib/remote-endpoint.js';

export const GET = config.spec;

// /api/remote/[...rest]/+server.ts
import { config } from '$lib/remote-endpoint.js';

export const fallback = config.router;

I think you could get basically all the way there with an API like this. Doesn't mean we shouldn't do more to support it in SK but it also could unblock you faster than we could -- we're going to be focusing on stabilizing async Svelte and remote functions' basic stuff first.

[ixxie]

I'm not sure what the overall solution to this looks like. I definitely think OpenAPI support and "I want to expose this remote function as an endpoint for other apps" are things we're going to look into.

Yeah I am definitely not sure either, just threw the first thing that came to mind.

For now, I would recommend creating your own simple wrapper function [...]

I think you could get basically all the way there with an API like this. Doesn't mean we shouldn't do more to support it in SK but it also could unblock you faster than we could -- we're going to be focusing on stabilizing async Svelte and remote functions' basic stuff first.

I don't have any urgent need for this. The idea just seemed to click and I wanted to drop an issue here so its not forgotten. I would keep this approach in mind if this ever becomes pressing though!