03 Creating Collections

title: "Creating Collections" description: "Create Postman collections with effective naming, descriptions, and organization. Learn collection creation from scratch, from examples, using the API Builder, and importing OpenAPI specifications." weight: 3 date: 2026-06-28 lastmod: 2026-06-28 tags: [api-development, postman] }

Postman collections start from scratch, from examples, from API schemas, or by importing OpenAPI/Swagger specs. Effective collection naming and descriptions turn collections into living documentation for your API.

What You'll Learn

• Creating collections from scratch
• Importing OpenAPI/Swagger specifications
• Using the API Builder for collection generation
• Naming conventions and descriptions
• Collection templates and examples

Why It Matters

Well-named and described collections serve as API documentation. Importing OpenAPI specs saves hours of manual work. Good organization makes collections usable by the whole team.

Real-World Use

Postman's API Builder imports OpenAPI 3.0 specs and generates collections automatically. Companies like Trello and Twitter provide Postman collections generated from their OpenAPI specs.

flowchart LR
    Create[Create Collection] --> FromScratch[From Scratch]
    Create --> FromSpec[From OpenAPI Spec]
    Create --> FromExamples[From Examples]
    Create --> APIBuilder[API Builder]
    FromScratch --> Name[Name & Describe]
    FromSpec --> Parse[Parse OpenAPI]
    FromSpec --> Generate[Generate Requests]
    APIBuilder --> Sync[Sync with API Changes]

Teacher Mindset

Start collections from OpenAPI specs when available. Name collections clearly with the API name and version. Write descriptions that explain the API's purpose. Use consistent naming for requests.

Code Examples

// Example 1: Collection metadata in exported JSON
{
  "info": {
    "name": "Petstore API v3",
    "description": "Collection for the Petstore API. Covers CRUD operations for pets, orders, and users.\n\nBase URL: https://petstore.swagger.io/v3",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  }
}

// Example 2: Programmatic collection creation
const collection = new Collection({
    name: 'E-Commerce API',
    description: 'Collection for testing the e-commerce platform'
});

// Add requests programmatically
collection.items.add({
    name: 'Get All Products',
    request: {
        method: 'GET',
        url: '{{base_url}}/api/products',
        header: [{ key: 'Accept', value: 'application/json' }]
    }
});

# Example 3: Import OpenAPI spec via CLI
# Using Postman CLI to import
postman api import --spec petstore.yaml --collection-name "Petstore API"

# Using Newman with Postman API
curl -X POST https://api.getpostman.com/collections \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -d @collection.json

Common Mistakes

• Not importing from OpenAPI specs when they exist
• Using generic names like "API Tests" without version or context
• Not adding descriptions to collections and requests
• Importing specs without reviewing generated requests
• Creating collections without considering the folder structure

Practice

1. Create a collection from scratch named "My API v1".
2. Import an OpenAPI spec (use petstore.swagger.io) and examine the generated collection.
3. Add a description to the collection explaining its purpose.
4. Rename requests to follow a consistent convention.
5. Challenge: Create a collection template with folders for CRUD operations and shareable variables.

FAQ

Mini Project

Import the Petstore OpenAPI spec into Postman. Organize the generated requests into folders (Pet, Store, User). Add descriptions to each folder. Set collection-level variables for base URL. Add examples for the create pet request.

What's Next

Next, you will learn about folder structuring within Postman collections.