Idea: Add typings/schema-definitions to postman collections and use it on requests

[german1608]

Hi, this is an idea for a project (that I'd like to implement) for GSoC

Description

Extend postman collection schema with another (or several) attribute that let users define requests and responses schemas (we could start with json) to be used in collections' requests objects. This allows us to type-check postman requests with a warning (because the user might want to test a 400 http response, for example).

Related ideas

• Collection-level codegen

Motivation

Because the two following reasons:

Early detection of errors in collection development

I've made several mistakes in the past using postman to make api calls just because I was mistakenly using an incorrect param, for example. Sometimes api responses does not provide enough feedback to fix the error (400 http status with empty response for example). Although this is not postman' fault, it could be nice that it let us know where are we wrong.

Codegeneration

There are some programming languages tools to create api clients (for example retrofit in java/kotlin) that are really good and powerful to use, but the main problem on implementing codegenerators for these tools is that they need to define custom classes or data types to be used properly, which, at this moment without this issue's feature, it can be implemented really generic. For example, a postman POST request to http://my-api/endpoint that receives a json {"a": "string"} and receives a response {"response": int} can generate retrofit with kotlin code the following way:

data class Request(val a: String)

interface ApiClient {
  @POST("endpoint")
  fun endpoint(@Body request: Request): String
}

Look that the return type is String because, as far as I know (probably I'm mistaken), postman doesn't save any information in their collection schema about responses, and to be generic as possible it can return String and let de-serialization happen later, as @HeshamAmer susggestion here.

Also look that the Request class name is really generic and works in this case because this is a single request codegen. But how can we improve this to achieve re-usability when we try to codegen a whole collection? I think typings can help doing so by generating for each schema definition a data type or class and using them as references in postman requests.

[ankit-m]

@german1608 this sounds very interesting. If I understanding correctly, you want to add a key (ex. expectedSchema) which stores JSON schema (say). This can be used to validate the request and response.

It is a very promising direction. Make sure that you distill this and create a proposal which provides a solid plan for 3 months. Moreover, it is crucial that you familiarize yourself with the codebase and make some contributions to the project before submitting your proposal.

Reach out to @codenirvana or @saswatds if you want to discuss this idea in detail.

Looking forward to reading your proposal.

[DasserBasyouni]

Hey @german1608 Wish you are doing great Have you reached anything on this project? I'm thinking to do the same idea. Maybe soon I will start so we might work on it together if you still on its road.