This article introduces the core concepts in Apidog, an API-first tool designed for efficient API design, testing, and collaboration. Many concepts differ from similar products like Postman. Understanding these will help you navigate Apidog's workflow effectively.Project#
A Project in Apidog is the primary unit of collaboration, containing modules, environments, test scenarios, and more. It serves as a container for all API-related work within a team.Key Components of a Project#
Modules: Logical groupings of endpoints and related components.
Environments: Variable sets for different deployment stages (e.g., development, staging, production).
Test Scenarios: Collections of requests for automated testing.
Endpoint Specifications: API documentation based on OpenAPI/Swagger standards.
Comparison with Postman#
| Apidog Concept | Equivalent in Postman | Description |
|---|
| Project | Workspace | Top-level organizational unit for collaboration. |
| Module | Collection Folder | Groups related endpoints. |
| Team | Team | Shared access and collaboration features. |
Projects enable seamless collaboration, allowing multiple users to work on APIs simultaneously while maintaining version control and access permissions.
Module#
A Module organizes endpoints logically within a project, similar to a "service" in microservices architecture. Each module represents a standalone OpenAPI specification file.Features of a Module#
Contains related endpoints, schemas, responses, and security schemes.
Configured with a Base URL per environment for automatic URL generation.
Supports import/export operations at the module level for better standards compliance.
When to Use Modules#
For microservices: Each service as a separate module.
For multiple APIs: Group endpoints by functionality or domain.
Default: New projects start with one module; add more as needed for multiple base URLs.
Modules align with OpenAPI Specification (OAS), facilitating integration with other tools and maintaining clean API boundaries.
Endpoint#
An Endpoint is the core element in Apidog's API-first approach, representing a specific API operation (e.g., GET /users/{id}).Endpoint Management#
Grouped in directory structures for organization.
Linked to endpoint cases for saved request examples.
Differences from Postman#
| Aspect | Apidog (Endpoint-based) | Postman (Request-based) |
|---|
| Basic Unit | Endpoint (API spec) | Request (individual call) |
| Spec Changes | Auto-updates cases and tests | Manual rewrite required |
| Structure | OAS extension with debugging | Separate specs and requests |
In Apidog, changes to endpoint specs propagate automatically to all dependent cases, reducing maintenance overhead through this specification-driven approach.
Environment#
An Environment manages variables and base URLs for different deployment contexts, enabling seamless switching between dev, staging, and production.Key Features#
Contains environment variables for dynamic values.
Supports multiple Base URLs per environment for microservices. Automatic URL construction: Base URL + Endpoint Path.
Base URL Example#
Suppose a project with three services:| Service | Base URL (Prod) | Endpoint Path | Full URL |
|---|
| User | https://user.example.com | GET /user/{id} | https://user.example.com/user/{id} |
| Order | https://order.example.com | GET /order/{id} | https://order.example.com/order/{id} |
| Product | https://product.example.com | GET /product/{id} | https://product.example.com/product/{id} |
No need for manual {{BaseUrl}} placeholders; Apidog detects the module and applies the correct base URL automatically.
Request#
A Request is a standalone API call, not tied to endpoint specs, similar to Postman's requests.Request Capabilities#
Parse successful requests into endpoint specs. Use for ad-hoc testing or undocumented APIs.
Requests provide flexibility for scenarios where API specs aren't predefined, bridging the gap between design-first and request-first workflows.
Test Scenario#
A Test Scenario executes batches of requests, akin to Postman Collections, with advanced automation features.Features#
Advanced Capabilities#
Test reports and performance testing.
Test scenarios auto-sync with API spec changes, ensuring tests remain valid as APIs evolve.
Design-first Mode & Request-first Mode#
Apidog's APIs module features two modes that can be switched at the bottom left corner of the interface: Design-first Mode and Request-first Mode.Both modes provide similar functionalities but with different interfaces, catering to different team workflows.Design-first Mode#
Recommended for teams practicing API-design first.
Define API specs before development and testing.
Ideal for planned, specification-driven projects.
Request-first Mode#
Suitable for teams focusing on backend development first.
Create requests, then generate specs from successful calls.
Perfect for undocumented APIs or third-party integrations.
Summary#
Understanding these core concepts will help you leverage Apidog's API-first approach for efficient design, testing, and collaboration. Start with creating a project, organize endpoints into modules, define environments for different stages, and build test scenarios for automation.For further reading, explore the linked documentation pages or try Apidog's interface to see these concepts in action.
Read to Kick-off?#
Start from Scratch
Get Started with Apidog from ScratchMigrate to Apidog
Start by migrating to Apidog 
