Feature(farrow-restapi): combine request schema and response schema to be api schema.

[Lucifier129]

For now, farrow-http just supporting the request schema.

We can use farrow-schema to describe the request and response of all the RESTFul API and integrate it with something like oepnapi. And seamless reusing the schema/type of all Apis in client-side for implementing type-safe fetcher.

The server-side

import { RequestType, ResponseType, toRouter } from 'farrow-restapi'

const GetUserRequest = RequestType({
  url: '/user?<id:int>'
})

const GetUserResponse = ResponseType ({
  success: Boolean,
  message:  String,
  data: {
    id: Number,
    name: String,
    email: String  
  }
})

const GetUserApi = {
  request: GetUserRequest ,
  response: GetUserResponse 
}

const Apis = {
  getUser: GetUserApi
}

const getUserRouter = toRouter(GetUserApi)

getUserRouter.impl(request => {
  // response should be GetUserResponse 
})

The client-side

The schema of API can generate an API client for client-side

import { createFarrowApiClient } from 'farrow-restapi-client'

let client= createFarrowApiClient(Apis, {
  baseurl: '/path/to/base'
})

client.getUser(GetUserRequest) -> Promise<GetUserResponse>

[ianmartorell]

Would this allow to use a typed API client on a frontend project that's separate from the backend? Like a create-react-app project. I'm currently achieving this using Express and customized versions of the packages in https://github.com/rawrmaan/restyped. I leverage yarn workspaces to import the backend workspace (which exports an API typescript interface) from the frontend workspace. It works great, but it feels a little hacky in some places. I can give a more in-depth explanation on the whole setup if needed.

I'm really liking what I have seen from Farrow thus far, so I'd like to consider it for future projects!

[Lucifier129]

Would this allow to use a typed API client on a frontend project that's separate from the backend?

Yes, that is the goal.

It will provide at least three ways to share the server-side schema/type with the client-side

• via npm package. We can publish the schema of the server project, and install it in any frontend project.

• via monorepo. Put server project and frontend project together in one git repos, and share the same schema written by farrow-schema. In the server project, farrow-restapi will use the schema as the spec/interface to implement; In the frontend project, farrow-restapi-client will use the schema as the source/contract to consume/fetch

• via introspection. Similar to GraphQL, farrow-restapi will provide a special api for introspection. We can use the response of introspection to generate TS code via a compiler tool or rebuild the TS type via type infer

[uinz]

Prisma's introspect has a very good experience

We can try to use the OpenAPI(swagger3) specification, so that clients in other languages can also consume

[Lucifier129]

@uinz Good point! Thanks for sharing!