January 2025 Summaries

API linting is a crucial process for ensuring the quality and consistency of APIs, similar to how linting is used in source code to enforce rules and best practices. Over the years, API linting has evolved from relying on extensive, often outdated API Style Guides to more automated and efficient methods. Tools like vacuum, an open-source API linter built in Go, enable developers to validate APIs against industry standards and custom rulesets, improving the development workflow significantly. Vacuum supports Spectral rulesets, offering portability and efficiency, and can be integrated into continuous integration systems to automatically check API changes in pull requests, ensuring that only valid, secure, and well-documented APIs are deployed. This automated approach not only helps maintain API quality but also aids in avoiding security vulnerabilities and maintaining consistency across large teams.

Speakeasy and Bump.sh have become the first vendors to officially support OpenAPI Overlays, a specification they believe can revolutionize various use cases. Speakeasy, a platform for building API SDKs, utilizes OpenAPI to create robust SDKs and enhance API documentation with custom code examples, Terraform providers, and end-to-end testing. These tools are designed for OpenAPI but also function with AsyncAPI through Bump.sh. Recently, Speakeasy released a guide showcasing the capability of Overlays to populate language-specific examples via the x-codeSamples extension, and the platform can generate both SDKs and Overlays containing these examples. With CI integration, the process is automated to ensure SDKs and documentation are always current with the latest API structure and contracts, providing seamless updates and implementation across supported languages.

In 2024, the collaboration between tech writers and engineers emphasized the importance of making APIs discoverable and well-documented, addressing the challenge of poorly documented partner APIs. The year saw significant developments, such as the introduction of Overlay Specification support compatible with OpenAPI and AsyncAPI, which enhanced the flexibility of API definition files. Bump.sh also launched a free API guides and tutorials website, emphasizing their commitment to API specification evangelism, and introduced the API Explorer to simplify API interactions. New features improved API catalog management, SEO through enhanced sitemaps, multiple SSO connections, and user feedback integration. The company continued its support for open-source projects and made a step towards open-sourcing some of its code, notably with the release of cors-toujours, a lightweight HTTP proxy server. Team growth and community engagement through conferences and quarterly meetings were also highlights, reflecting a balance between remote work and in-person collaboration.

Bump.sh has introduced a new feature called the API Explorer, a web-based interface that enables users to send HTTP requests to documented APIs directly from their browsers, while addressing the challenges posed by CORS (Cross-Origin Resource Sharing) restrictions and ensuring user privacy. The company developed an open-source proxy solution named cors-toujours to solve these challenges, allowing requests to be routed through a dedicated proxy server that avoids CORS issues without exposing user data to the main application infrastructure. By maintaining transparency and security, cors-toujours operates without logging user data and is available for public auditing under the AGPL license. It includes a simple authorization layer using JWT tokens to prevent misuse, ensuring that only authorized requests are processed. This solution allows Bump.sh to enhance API usability without compromising on security or privacy, inviting the community to use, study, and contribute to the project on GitHub.

Bump.sh is a cloud-hosted SaaS platform operated by It Ducks SAS, based in France, designed for publishing, hosting, and comparing API documentation derived from OpenAPI and AsyncAPI specifications. The service emphasizes security, privacy, and operational controls, focusing on handling documentation artifacts without accessing customer production systems or processing runtime data. Hosted on Heroku (AWS) with a managed PostgreSQL database provided by Crunchy Data, Bump.sh ensures data residency in Europe and supports SSO and centralized access through WorkOS. It incorporates automated dependency monitoring, static security analysis, and mandatory code reviews to manage application and supply chain security. While the platform lacks formal third-party certifications like SOC 2 or ISO 27001, it offers transparency in architecture and allows enterprise customers to conduct penetration tests annually. Security and compliance information is readily available through various dedicated documents, and the company's infrastructure is monitored for incidents, although it doesn't conduct formal vendor security audits.