OpenAPI

[brillout]

Both ways are interesting:

1. Generating an OpenAPI spec from telefunctions.
2. Generating telefunctions from an OpenAPI spec.

@nitedani Curious: could Telefunc automatically generate your setup?

CC @louwers.

[nitedani]

In my project I'm using OpenAPITools/openapi-generator, which is a Java project, its cli requires Java to be present/you can use the docker image they provide. It would be nice to have, but I don't know how to feel abut the Java dependency. Maybe as a separate cli package it could work? Generating telefunctions would be very simple that way.

This project could be useful too, it's written in typescript.
It can be extended to generate .telefunc files, using the fetch functions and schema files it already generates.

[brillout]

@nitedani Neat 👍. It'll most likely be a separate package but, yea, a TS dependency would be better.

[louwers]

Example OpenAPI with Swagger UI: https://editor.swagger.io/

The way I imagine OpenAPI intergration is not to generate telefunctions, but to generate an OpenAPI spec from *.telefunc.ts files. This way Telefunc can (also) be used as a convenient way to quickly create an API that non-TS clients can use.

Brain dump:

• OpenAPI has support for JSON Schema: https://swagger.io/docs/specification/data-models/keywords/. This may be useful for supporting complex types.
• The JSDoc comment will be used as description.
• By default each API / RPC route is grouped by filename, so pet.telefunc.ts would create the group pet, but I plan on making this configurable with a function. (telefuncFilePath: string) => string | undefined where if a string is returned, the default will be overridden.
• By default Telefunc would be a POST HTTP method with path /telefunc/${groupName}/${telefuncName}. The JSON body would contain the parameters.
• Maybe it should be possible to also use the GET method for some Telefunctions. This allows for caching. Maybe another configuration option (telefuncName: string) => 'GET' | 'PUT' | 'POST' | 'DELETE' where you can for example use: (telefuncName) => telefuncName.startsWith("onGet") ? 'GET' : 'POST'.
• For GET requests the parameters should be a simple numbers or strings so they can be passed in the path instead of in the body.

[brillout]

Sounds good 👍.

• By default each API / RPC route is grouped by filename, so pet.telefunc.ts would create the group pet, but I plan on making this configurable with a function

Spontaneously/naively I'd lean towards convention over configuration here and enforce api/$group.telefunc.ts. Do we need to make it configurable? Maybe I'm missing use cases for configurability.

• Maybe it should be possible to also use the GET method for some Telefunctions.

I was thinking of having a new cache() decorator for that.

// api/pet.telefunc.ts

import { cache } from 'telefunc'

cache(findOne)
export async function findOne(id: number) {
  /* ... */
}

• For GET requests the parameters should be a simple numbers or strings so they can be passed in the path instead of in the body.

I wonder what the drawbacks would be to not respect REST principles. For example:

• GET https://api.animals.com/pets/${JSON.stringify(telefuncArgs)} (e.g. GET https://api.animals.com/pets/[{"petId":3}]) instead of:
• GET https://api.animals.com/pets/${firstSimpleArgument} (e.g. GET https://api.animals.com/pets/3).

If we deviate from REST we can make things simpler, but maybe that'd be inconvenient for OpenAPI clients.

[brillout]

I wonder what the drawbacks would be to not respect REST principles.

I think we can first not care about REST principles (e.g. GET https://api.animals.com/pets/[{"petId":3}] instead of GET https://api.animals.com/pets/3) and see how it goes. We can add features to make the API more RESTful afterwards, if users/OpenAPI/Swagger need it.