Design your APIs with Postman Collections

Define types in your collection to add more details to request parameters, headers, and bodies in an HTTP collection. Define types such as data type, format, and possible values. You can also specify if a component is required. Before you send a request, Postman checks it using the defined types and identifies possible issues. All the details appear in the collection’s documentation for both API developers and consumers.

Types are available for HTTP collections with application/json type request and response bodies. It isn’t available for other request protocols or body types.

When you’re ready to verify the quality of your APIs and deploy to an API gateway, generate an API specification from your collection and keep them in sync.

Types aren’t supported in collections connected to Git repository.

Define types in your collections

You can define types in your requests that describe your API. This enables you to design and test your APIs using the Postman Collection format you’re familiar with. Types can help your team and API consumers understand your API and send valid requests. Learn how to add types to parameters and headers.

You can also add body data to a request or saved example and generate a schema from the body data. The schema includes types based on the body data. Optionally, you can add descriptions or specify required types. Learn how to add types to body data.

View types and documentation

Your team and API consumers with access to a collection with defined types can view them in the collection and its documentation. Postman notifies you if the request parameter, header, or type in the body data is required to send the request. You can also hover over a parameter, header, or type in the body data to learn more.

Before you send a request, Postman checks the value against the defined types and notifies you if the value isn’t valid. Also, anyone with access to the collection can view details associated with your parameters, headers, and bodies in your collection’s documentation.

Learn how to view types and documentation in a collection.

Generate a specification from a collection

Once you’ve designed and tested your APIs in a collection, automatically generate an OpenAPI 3.0 specification in Spec Hub. You can use the specification to check your APIs’ quality and deploy to an API gateway. Generated specifications have paths, components, and more based on your collection. Postman recommends that you add types to the collection to generate a complete OpenAPI 3.0 specification.

When you make changes to the collection, update the generated specification with your latest changes. This ensures team members relying on the specification can access the latest iteration of your APIs.

Learn how to generate a specification from a collection and keep them in sync.