Path params, array output, empty input, query params with POST

[linde12]

Hi! I was looking for something that enforced zod types to my input body/query params and automatically caught exceptions thrown from my async handlers and i found this. Looks awesome and at first glance it functions well. After diving a bit deeper though i've run into some problems:

• I can't find any documentation on how you access & validate express route path values. E.g. express.get('/users/:id', ...) - how do i set a schema for id and access its value?
• I can't find any documentation on how you work with array outputs [1]
• I can't seem to create an endpoint without any inputs, e.g. a GET route with not query params - is this a conscious decision that you always have to define an input schema? Can't find any documentation on it.
• When using DependsOnMethod i can specify a certain endpoint for e certain method, but i still have to set the method property of the endpoint. Concious decision? [2]
• There is no example of a POST with query parameters. Is this not supported? I know of several APIs that use this and since im doing some vetting i just want to know :-)

1. Array output error

2. DependsOnMethod

const post = defaultEndpointsFactory.build({
  description: 'Create todo',
  method: 'post', // explicitly have to say that it is a post method
  input: CreateTodoInput,
  output: CreateTodoOutput,
  handler: async ({ input: todo}) => {
    todos.push({ ...todo, id })
    id++;
    return {...todo, id }
  },
})

export default new DependsOnMethod({
  post,
})

Most of these questions probably have a simple answer, and this issue is not about the problem themselves (if any) but the lack of documentation. Not trying to sound like a jerk here, i'm just happy i found this. Great work 👍

[RobinTail]

Hello @linde12 .

Thank you for your feedback. I am happy to answer your questions in order.

I can't find any documentation on how you access & validate express route path values. E.g. express.get('/users/:id', ...) - how do i set a schema for id and access its value?

You can find the complete answer here: #73
Basically you should do this:

const myRouting: Routing = {
  users: {
    ':id': myEndpoint // <— connected to /users/:id 
  }
};

And in order to obtain the value of :id you need a paramsProviderMiddleware. You will find an example at the link mentioned above.

I can't find any documentation on how you work with array outputs [1]

Shortly: you should pass the array to an object property.

// instead of
return [1,2,3];
// do this
return {
  myData: [1,2,3]
}

This is an intentional limitation: the output of the Endpoint should be z.object() or union/intersection of objects.
The error [1] you get is about this constraint.
Besides that it's usually better to return objects from the beginning. As you develop and further develop your API, you may need to add other data or meta information. This way you can maintain backward compatibility for longer.

I can't seem to create an endpoint without any inputs, e.g. a GET route with not query params - is this a conscious decision that you always have to define an input schema? Can't find any documentation on it.

That should be easy. Please try this:

const myEndpoint = myEndpointsFactory.build({
  method: 'get',
  input: z.object({}),
  ...
});

So just use an empty object schema. The object being validated as input in case of GET request is req.query of express.
By the way, you can use the same pattern for middlewares without inputs.

When using DependsOnMethod i can specify a certain endpoint for e certain method, but i still have to set the method property of the endpoint. Concious decision? [2]

Yes. This is to make it possible to implement many-to-many relationships between the available route methods and the supported handler methods. Here is an example of such case:

// example of different I/O schemas for /v1/user
const routing: Routing = {
  v1: {
    user: new DependsOnMethod({
      get: myEndpointA, // GET —> handler for GET and DELETE
      delete: myEndpointA, // DELETE —> handler for GET and DELETE
      post: myEndpointB, // POST —> handler for POST and PATCH
      patch: myEndpointB, // PATCH —> handler for POST and PATCH
    })
  }
};

There is no example of a POST with query parameters. Is this not supported? I know of several APIs that use this and since im doing some vetting i just want to know :-)

You're right. There is no such example. Currently express-zod-api is processing only .body (and optionally .files) of the POST requests. It is usually better to transfer all the data in one way and in the case of POST taking advantage of the body. However, I think I can ponder this and maybe add an extra option in the config so you can receive both .query and .body to input.

Please let me know if I managed to provide you with required answers or something need to be additionally clarified.

[linde12]

Hi @RobinTail ! Thank you for your in-depth reply! I am clear on all things except:

When using DependsOnMethod i can specify a certain endpoint for e certain method, but i still have to set the method property of the endpoint. Concious decision? [2]

Yes. This is to make it possible to implement many-to-many relationships between the available route methods and the supported handler methods. Here is an example of such case:

// example of different I/O schemas for /v1/user
const routing: Routing = {
  v1: {
    user: new DependsOnMethod({
      get: myEndpointA, // GET —> handler for GET and DELETE
      delete: myEndpointA, // DELETE —> handler for GET and DELETE
      post: myEndpointB, // POST —> handler for POST and PATCH
      patch: myEndpointB, // PATCH —> handler for POST and PATCH
    })
  }
};

I think i was a bit unclear in my question, but i'm wondering if i still have to set the method or methods property on myEndpointA even when using it with DependsOnMethod cause when i didnt i would get a typescript error. Looking back i don't see this as an issue anyway 😄 Thank you again!

[RobinTail]

Hello @linde12 .

...i'm wondering if i still have to set the method or methods property on myEndpointA even when using it with DependsOnMethod...

Yes, you have to.
The Endpoint exists regardless of Routing. Basically, it "does not know" which route you're connecting it to, or even you are not connecting it at all.
In this regard, you should consider DependsOnMethod as a Routing helper, and not an Endpoint. At least that's the design at the moment.

I hope I managed to clarify this topic for you.
Please let me know if you have any other questions on the issue.

[RobinTail]

Hello @linde12 ,

I made a PR on the new config option that I believe will help you to achieve the desired behavior: including req.query to input along with req.body for POST requests.

The feature will be released in version 2.8.0. The issue will be converted to discussion.

[RobinTail]

The feature has been released in version 2.8.0 🎉

[RobinTail]

I came to conclusion that method of Endpoint is redundant in case of using DependsOnMethod.
I don't want to make it optional in order to avoid mistakes during development, but probably there can be a specific value.

[RobinTail]

Now supporting array response: #361 (comment)
(at your own risk).