Transforming Bugcrowd API Architecture for a Better Developer Experience
At Bugcrowd, we’re committed to providing a robust and reliable API for our customers. We’ve heard your feedback, and we’re excited to announce a series of significant improvements to our API architecture designed to enhance performance, simplify usage, and streamline future updates. This blog post outlines the key changes we’re implementing and what they mean for you.
The set of improvements includes:
- Structural Improvements: Reducing the dependency on deeply nested includes for more efficient API calls.
- New Serializers: A new set of serializers to eliminate complex queries and significantly boost performance.
- Versioning System Fix: Transitioning from a date-based versioning system to a semantic versioning (SemVer) system. This change removes the need for serializer transformers, simplifying the developer process and improving stability.
Refining API Format and Structure
While we currently use JSON:API, we recognize that certain aspects of our implementation have made it challenging to use. Our goal is to make our API more intuitive and flexible.
We have made structural changes that will help to reorganize our API endpoint structure to ensure resources are treated as independent entities, making them easier to access and manipulate with their own dedicated endpoints. These resource entities will be supported by standard CRUD operations, along with improved documentation.
These changes will be rolled out incrementally in the future releases.
Simplifying Serializers
We have conducted a comprehensive audit to simplify our serializers and effectively addressed some of the performance issues. We have improved the serializer performance through better optimization, resulting in a quicker response.
A Smarter Versioning System
Our existing versioning system has limitations, only allowing for major versions and complex transformations between them. We are transitioning to a more standard and flexible approach to enhance your experience:
- Standardized Versioning: We will adopt a semantic versioning (X.Y.Z) system. In this system, major versions (X) will signify significant, non-backwards compatible changes, while minor (Y) and patch (Z) versions will be backwards compatible.
- Customer API Keys Pinning: Customers will only need to pin their API keys to major versions. This allows us to release minor and patch updates without requiring any action on your part. When minor version or a patch is released, there is no need for the customers to update their API token and they automatically get those updates
- Backward compatibility: A major version will always be backward compatible with any changes introduced in minor and patch versions. Customers will consistently be on the latest release, incorporating changes from minor and patch versions. Documentation and digests will always reflect the latest changes within a major version.
- Clear Changelogs: Minor and patch versions will primarily serve to track changelogs, providing clear visibility into all updates.
Consolidating Existing Versions
We plan to consolidate our current fragmented date-based versions into a single major release (V1). The current date-based API versions:
- API Version 2025-04-23
- API Version 2025-02-25
- API Version 2024-08-15
- API Version 2024-07-11
- API Version 2024-03-27
- API Version 2024-02-12
- API Version 2024-02-09
will all be consolidated and pinned to a single V1 major version. This consolidation will significantly accelerate API calls by eliminating intermediate serializer transformations.
Current API customers will be automatically transitioned to the major version V1, and their API keys will be updated and pinned to V1. Although there are structural changes to the API, there are no alterations to the API functionality or the endpoints currently in use from the date-based versions.
A Predictable Release Cadence
To provide greater predictability, we are establishing a clear release cadence:
- Major Version (Every Couple of Years): Introduces non-backwards compatible changes to the API structure or format.
- Minor Version (Every Quarter): Includes new functionality that is backwards compatible within the current major version.
- Patch (Daily, Weekly, Monthly): Small fixes, enum value changes, and other backwards compatible updates.
API Support Policy and Introducing Maintenance Mode
When a new major release is introduced (for example, V2), the current API major release (V1) will transition into “maintenance mode.” Both major releases, V1 and V2, will continue to be supported.
When a version enters maintenance mode, it will receive only bug fixes and patches, with no new features. This will be publicly communicated, allowing customers ample time to transition to the latest versions. We may also deprecate specific relationships, fields, or enums within a version in maintenance mode.
A Clear Deprecation Strategy
We are developing a comprehensive deprecation strategy to guide us through any destructive changes with minimal impact on our customers. This strategy will address two primary scenarios:
- Deprecating Models/Relationships within a Version: In rare instances where we remove a model or relationship, we may patch the API to return a deprecated message.
- Deprecating Entire API Versions: For significant changes requiring customers to migrate to a new major version, our new versioning system will facilitate a smoother transition.
Immediate Next Steps
We are already in motion!
Over the next few weeks, we will migrate current API users to the new major release V1 and update their API keys to pin to this new major release. This process will be entirely transparent to users, requiring no action on your part. We will communicate with you directly via email to your Organization Owners and through your Bugcrowd account team. Should you have any questions, please feel free to reach out to us or create a support ticket.
We are confident that these architectural improvements will significantly enhance your experience with the Bugcrowd API, providing greater stability, performance, and ease of use. We are enthusiastic about these changes and look forward to collaboratively building an even better API!
