apicollective/apibuilder

This system is an API Builder platform that manages the lifecycle of API specifications, organizations, and applications. It provides a REST API and web interface for users to define, validate, and version APIs using Swagger and Avro, while automatically generating client code and database access layers. The platform handles user authentication, subscription management, and background tasks for synchronization and data maintenance.

15 changes.

The project was initialized with a core structure, CI/CD pipelines, and comprehensive documentation. A new API layer was built using Scala 3 and Play 3, featuring controllers for organizations, users, and code generation, alongside a generated DAO layer with centralized authorization. Supporting infrastructure included email delivery, service diffing utilities, and extensive test coverage for both the API and shared library components.

15 changes.

This period focused on migrating the codebase to Play 2.9 and Scala 3, involving the regeneration of API client libraries and model conversions to ensure compatibility with the new runtime environment. The work included refactoring controllers and library components to use constructor-based dependency injection, introducing a structured actor-based system for background tasks, and adding comprehensive test coverage for database access objects and query parsing. Additionally, initial application configuration, routing, and public assets were established alongside new UI features for managing user accounts and application settings.

23 changes.

This period focused on extending the API Builder ecosystem by introducing parsers and validators for Avro IDL and Swagger specifications. Simultaneously, the application migrated its data access layer to a generated DAO system, replacing manual implementations with auto-generated code for core domain entities and generator services.

New invariant checks have been added to monitor data consistency and operational health. The system now verifies that deleted services have corresponding deleted generators, ensures that old deleted records in organizations, applications, and versions are purged according to their respective retention periods (12, 6, and 6 months), and detects tasks that have not been attempted or completed within expected timeframes.

api/app/invariants · high confidence

A new query parsing library has been introduced in the API application to handle search queries. It allows users to specify organization filters using the 'org:foo' syntax in the query string, while unrecognized keys are treated as plain text. The parser splits input by whitespace and colons, extracting text tokens and organization keys into a structured Query object.

api/app/lib/query · high confidence

A new example Avro protocol definition (example.avdl) has been added to the avro module. This file demonstrates the use of union types within record fields, specifically showing a 'Members' record containing a 'user' field that can be either an 'Employee' or a 'Contractor'. It also includes definitions for enums, fixed types, and error types to illustrate broader Avro schema capabilities.

avro · high confidence

New data access objects have been generated for the \generators.generators\ and \generators.services\ database tables. This introduces \GeneratorsDao\ and \ServicesDao\ (extending \BaseGeneratorsDao\ and \BaseServicesDao\ respectively) which provide methods for querying, inserting, and managing records for generators and services, including support for pagination, filtering by GUID, and handling soft deletes via \deletedAt\ fields.

generated/app/db/generators · high confidence

The \generated/app/db\ area now includes generated Data Access Objects (DAOs) for core domain entities such as Applications, Attributes, Changes, Email Verifications, Membership Requests, Memberships, and Organization Attribute Values. These files provide the database interaction layer for these entities, enabling the application to query and manage data in the corresponding PostgreSQL tables.

generated/app/db · high confidence

The API service now includes its foundational configuration and routing files. The \application.conf\ hierarchy (base, dev/test, production) sets up PostgreSQL connectivity, CORS policies, email delivery, and Pekko actor dispatchers, while sourcing secrets from environment variables in production. The \routes\ file defines the complete set of API endpoints, exposing resources for applications, organizations, users, memberships, generators, tokens, and subscriptions, along with code generation and validation endpoints.

api/conf · high confidence

The application now includes its core configuration files and route definitions. Environment-specific settings for development and production are defined in \application.conf\ and \application.production.conf\, managing API endpoints, OAuth credentials, and secret keys. The \base.conf\ file configures the Play framework by disabling CSRF, host, and security headers, sets the maximum memory buffer, and defines the Pekko actor thread pool parallelism. Additionally, the \routes\ file establishes the URL mappings for the application, covering authentication flows, organization and application management, documentation pages, and code generation endpoints.

app/conf · high confidence

This change introduces the foundational public-facing assets for the application. It adds a new JavaScript utility file (\app/public/javascripts/util.js\) that handles client-side interactions, including confirmation dialogs for delete actions, POST form submissions for specific links, and AJAX updates for generator visibility and enablement settings. Additionally, it establishes the visual design by adding a main stylesheet (\app/public/stylesheets/main.css\) that defines the layout for the sidebar, main content area, and error states, alongside brand assets including SVG logos and an icons directory.

app/public · high confidence

The repository has been initialized with the core project structure, including the addition of a Jenkinsfile for CI/CD pipeline configuration, Docker-related files (.dockerignore, .delta for deployment definitions), and standard configuration files (.java-version, .scalafmt.conf). Documentation files such as README.md, DEVELOPER.md, DEPLOY.md, CONTRIBUTING.md, and SWAGGER.md have been added to guide users and developers on setup, deployment, and API specification support.

(repo-wide) · high confidence

The \avro/src/main\ module now includes core components to parse Avro IDL files and validate them against the API Builder specification. This adds \Parser\ to convert Avro schemas into API Builder service models, \AvroIdlServiceValidator\ to handle validation logic using \ValidatedNec\, and supporting utilities like \ApiBuilder\ and \SchemaType\ to map Avro types to API Builder types. Users can now ingest and validate Avro IDL definitions within the API Builder ecosystem.

avro/src/main · high confidence

The swagger module now includes a complete set of new Scala classes to parse Swagger specifications and translate them into the internal API Builder service model. This adds the core Parser and ModelSelector for handling definition resolution and dependency ordering, along with a suite of translators (Model, Field, Operation, Parameter, Response, Resource, etc.) that map Swagger constructs to API Builder types. It also introduces SchemaType for type mapping, SwaggerData for preserving Swagger-specific metadata as attributes, and SwaggerServiceValidator for input validation.

swagger/src/main · high confidence

The application now includes a suite of new background processors to handle specific operational tasks. The CheckInvariantsProcessor runs hourly to verify system invariants and emails administrators if errors are detected. The PurgeDeletedProcessor handles the cascading soft-delete and permanent removal of old records for organizations, applications, and versions. The DiffVersionProcessor detects changes between API versions and notifies subscribers via email. Additionally, new processors manage user onboarding (UserCreatedProcessor), email delivery (EmailProcessor), application indexing (IndexApplicationProcessor), and generator service synchronization (SyncGeneratorServiceProcessor).

api/app/processor · high confidence

Added several new utility components in the api/app/util package to support core API builder functionality. This includes ApiBuilderServiceImportResolver for resolving and deduplicating service imports, BasicAuthorization for parsing session and token-based authentication headers, and GeneratorServiceUtil for synchronizing generator services with external clients. Additionally, new classes for session management (SessionHelper, SessionIdGenerator), database locking (LockUtil), random string generation (Random), and user agent formatting (UserAgent) have been introduced to standardize these operations across the application.

api/app/util · high confidence

The application now centralizes configuration management via a new \AppConfig\ and \Config\ wrapper, standardizing how required and optional settings (such as mail, Sendgrid, and Rollbar) are loaded and validated. A new email subsystem has been added, featuring an \EmailUtil\ for sending HTML emails via Sendgrid or local file delivery, and an \Emails\ service that handles subscription-based delivery with strict authorization checks to ensure users only receive updates for resources they can access. Additionally, a comprehensive \ServiceDiff\ engine has been implemented to compare two service specifications, detecting and classifying changes (breaking vs. non-breaking, material vs. not material) across models, enums, unions, headers, and imports, while \ExampleJson\ generation has been improved to correctly handle union types and discriminators.

api/app/lib · high confidence

The API now exposes a comprehensive set of new controllers in the \api/app/controllers\ directory, providing endpoints for managing Organizations, Applications, Users, Memberships, and Membership Requests, as well as handling Authentication, Password Resets, and Email Verification. Additionally, new controllers enable code generation via the Code controller, manage Generator Services and Generator With Services, handle Organization Domains and Attributes, and support Tokens, Subscriptions, and Batch operations for versions and applications. These controllers implement the \ApiBuilderController\ base trait, which standardizes authentication (anonymous, API key, session) and authorization checks (org member/admin roles) across all endpoints.

api/app/controllers · high confidence

Added three new service classes to handle specific batch operations and user verification flows. BatchDownloadApplicationsService enables users to download application data in bulk by validating and processing forms against internal DAOs. BatchVersionsLatestService provides an API endpoint to retrieve the latest version for up to 500 applications in a single request. EmailVerificationsService manages the confirmation of email verification tokens, including expiration checks and automatic acceptance of membership requests for users verifying via email.

api/app/services · high confidence

The client-tests area now includes a new Ruby script (copy.rb) to copy organizations, applications, and versions between Apidoc instances, alongside a comprehensive test runner (download-and-compile.rb) that generates and compiles client code for Play 2.2, Play 2.3, Play 2.4, Ning 1.8, Ning 1.9, and Ruby targets. Build configurations for these targets have been added or updated, setting sbt to version 0.13.9 and specifying Play sbt-plugin versions 2.2.3, 2.3.8, and 2.4.2.

client-tests · high confidence

The application now sends email notifications for several critical user actions and system events. Users will receive alerts when a new application is created, when an email address verification is required, and when a password reset is requested. Organization members are notified when someone joins, when a membership request is accepted or declined, and when an API version is updated with breaking or material changes. Additionally, system administrators receive reports on invariant check results.

api/app/views · high confidence

Added new automation scripts to streamline API and database operations. The \script/update\ script uploads API JSON specifications to the API Builder platform, handling dependency resolution, version tagging via \sem-info\, and optional profile-based uploads. The \script/update\_daos\ script extends this workflow to the DAO specification directory, uploading specs and subsequently generating Scala/PostgreSQL database code using the \apibuilder\ CLI. Supporting libraries (\script/lib/common.rb\, \ask.rb\, \tag.rb\) provide argument parsing, verbosity control, and interactive prompts for these processes.

script · high confidence

This change introduces a new set of web pages for managing core organizational resources. Users can now view and edit their account profile (email, nickname, name) via dedicated index and edit screens. Application settings are now managed through a new interface that allows changing application visibility and moving applications between organizations. Additionally, a new section has been added for managing global API attributes, including listing, creating, and viewing details for attributes used to enhance code generation.

app/app/views · high confidence

A new \lib\ module has been added to the project, containing shared Scala utilities extracted from the core generator. This includes type system definitions (Kind, Primitives, TextDatatype, VersionedName), text processing helpers (Text, UrlKey, FileUtils), validation infrastructure (ServiceValidator, ValidatedHelpers), and domain-specific models (Review, ServiceConfiguration, Pager). This structural change decouples these shared components from the main generator, allowing them to be reused and tested independently.

lib/src/main/scala · high confidence

The library components in app/app/lib have been refactored to use Play's dependency injection framework. Classes such as ApiClientProvider, Config, Github, and RequestAuthenticationUtil now accept their dependencies (like WSClient and Configuration) via constructor injection using javax.inject.Inject, replacing previous instantiation patterns. This change improves testability and modularity of the application's core utilities.

app/app/lib · high confidence

All controllers in the application have been rewritten to use constructor-based dependency injection via the \@Inject\ annotation, replacing the previous implicit or manual wiring. A new \ApiBuilderController\ base trait and \ApiBuilderControllerComponents\ interface have been introduced to centralize the injection of core components such as action builders (\Identified\, \Anonymous\), \ControllerComponents\, and \MessagesApi\. This change standardizes how controllers access request data, authentication utilities, and API clients, making the controller layer more modular and easier to test.

app/app/controllers · high confidence

The API now includes a custom error handler that ensures all error responses are returned as JSON, including a unique error ID for server errors to facilitate log correlation. Additionally, a logging filter has been added to record request details such as method, URI, status code, duration, and user agent for every incoming request.

api/app/play · high confidence

The core service now enforces stricter validation on API specifications, including rejecting JSON inputs with duplicate keys and validating that interfaces defined on models and unions actually exist. It also introduces a new import mechanism that fetches and validates external service definitions via URIs, ensuring that referenced types are resolvable across imports.

core · high confidence

The database access layer for generator services and generators has been refactored to use newly generated DAOs (ServicesDao and GeneratorsDao). This change introduces InternalGeneratorServicesDao and InternalGeneratorsDao, which wrap the generated data access objects to provide internal-facing methods for creating, validating, finding, and soft-deleting generator services and generators. Users interacting with these internal APIs will see the same functional behavior, but the underlying persistence logic is now handled by the generated DAOs, ensuring consistency with the rest of the codebase's data access patterns.

api/app/db/generators · high confidence

A new configuration file has been added to the .devops directory to define the API builder organization as 'apicollective'. This establishes the organizational context for API generation or management tools used in the development pipeline.

.devops · low confidence

A new DI module and factory implementation are added to wire the generator client for production and development environments. The \ProductionClientModule\ binds the \GeneratorClientFactory\ interface to \ProductionGeneratorClientFactory\, which uses Play's \WSClient\ to instantiate the generator client, ensuring the correct client implementation is used based on the application mode.

api/app/modules · high confidence

The application has adopted a new approach for database access by introducing a generated Data Access Object (DAO) layer. This change is evidenced by the addition of a Ruby script (\dao/run.rb\) that orchestrates code generation using an external tool (\dao\_generator\) based on JSON specification files (e.g., \psql-apibuilder.json\). These specifications define database models such as \user\, \password\_reset\, and \application\, along with their fields, primary key generation strategies (UUIDs), and PostgreSQL indexes. This shift replaces manual DAO implementations with auto-generated code, standardizing how data is persisted and retrieved for these entities.

dao · high confidence

The API Builder configuration and tracked file list have been updated to generate client code using the Play 2.9 and Scala 3 toolchain. This change replaces previous Play 2.8/Scala 2.12 generators with new \play\_2\_9\_scala\_3\_client\ and \play\_2\_x\_scala\_3\_json\ generators, ensuring that generated API models and clients are compatible with the upgraded framework versions.

.apibuilder · high confidence

The model layer in api/app/models has been refactored to replace previous data-access implementations with generated DAOs (e.g., InternalOrganizationsDao, InternalUsersDao). This change standardizes how models like ApplicationsModel, UsersModel, and OrganizationsModel retrieve and transform database records into API response objects, ensuring consistent data mapping and reducing manual query logic across the application.

api/app/models · high confidence

The application now uses a dedicated actor-based system to manage and execute background tasks, such as syncing generator services, checking invariants, and purging deleted items. This change introduces new actors (ScheduleTasksActor, TaskDispatchActor, TaskActor) and a Guice module to bind them, replacing previous ad-hoc scheduling mechanisms with a structured, retry-capable task queue that runs on specific dispatchers.

api/app/actors · high confidence

The database access layer has been refactored to use a new generated DAO pattern, introducing a suite of \Internal\*Dao\ classes (such as \InternalApplicationsDao\ and \InternalOrganizationsDao\) that wrap generated data access objects. This change introduces a centralized \Authorization\ system that enforces access controls by filtering queries for organizations, applications, tokens, and subscriptions based on user identity or public visibility. Additionally, a \Filters\ utility standardizes soft-delete and expiration logic across these data access objects.

api/app/db · high confidence

The generated Scala client libraries in the \generated/app\ directory have been updated to target Play 2.9 and Scala 3. This regeneration pulls in the latest API Builder service specifications (e.g., \apicollective/apibuilder-api\ v0.16.50, \apicollective/apibuilder-spec\ v0.16.74), introducing new models such as \Diff\ and \DiffType\ for application versioning, \TaskType\ for background job definitions, and \EmailData\ discriminators for notification payloads. The codebase also reflects spec changes including the removal of the deprecated \apidoc\ attribute, the addition of \attributes\ to responses and fields, and the support for union type discriminators and optional fields.

generated/app · high confidence

The generated conversion utilities in api/app/generated have been updated to support the upgraded runtime environment (Play 2.9, Scala 3, and Anorm 2.9 with parser combinators). These new files, such as ApicollectiveApibuilderApiV0Conversions.scala, provide the necessary implicit column parsers to correctly map PostgreSQL JSONB data (PGobject) to Play JSON JsValue instances within the application's database layer, ensuring compatibility with the new Scala 3 syntax and Anorm version.

api/app/generated · high confidence

The generated models in \lib/src/main/scala/generated\ have been regenerated to support the upgrade to Play 2.9 and Scala 3. This update includes new case classes and traits (such as \Annotation\, \Apidoc\, and \Application\) defined in \ApicollectiveApibuilderSpecV0Models.scala\, reflecting changes in the underlying API builder specification (v0.16.74). Users relying on these generated types will see updated signatures and potentially new fields, ensuring compatibility with the new Play and Scala versions.

lib/src/main/scala/generated · high confidence

Added empty \.exists\ marker files to the \app/models\ directories for both the Play 2.2 and Play 2.3 client test projects. This change ensures the model directories are tracked by version control, resolving a setup issue in the client tests.

_client-tests/play\_2\_2, client-tests/play\_2\3 · high confidence

Added comprehensive database access object tests; Added controller integration tests for API endpoints; Added service tests for batch downloads and email verifications; Added test coverage for API builder utilities and database access helpers; Added test coverage for Avro IDL service validation and parsing; Added test coverage for email authorization, JSON example generation, and service diffing; Added test coverage for processor components; Added test helper utilities for async operations, batch downloads, and organizations; Added test helper utilities for service configuration and validation; Added test infrastructure for mocking generator clients; Added test suite for Swagger parser and utility functions; Added tests for URL validation utility; Added tests for generator and generator service DAOs; Added unit tests for lib utility classes; Added unit tests for the query parser.

The build system has been upgraded to use Scala 3.7.3 and Play 3, replacing previous versions. This change updates core library dependencies including play-json to 2.10.6, avro to 1.11.1, circe to 0.14.9, and swagger-parser to 1.0.61. Additionally, the api and app modules now depend on sendgrid-java 4.10.3, postgresql 42.7.7, and the Datadog Java agent 1.53.0, while the app module uses flexmark 0.64.8 for markdown processing and commons-compress 1.28.0.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 37 → 39 (+2.0)
• Rubric changed (rubric-2026.09.8 → rubric-2026.09.16) — scores are not directly comparable.

• Code Health 90 → 90 (+0.0)
• Architecture 91 → 49 (-42.2)
• Maturity 30 → 47 (+17.2)
• Readiness 31 → 34 (+3.3)
• Security 39 → 39 (+0.0)
• Accessibility 40 → 40 (+0.0)

• Documentation: no installation or build instructions (app/app/views/doc/start.scala.html)
• Documentation: no project overview (app/app/views/doc/start.scala.html)
• Documentation: no usage examples (app/app/views/doc/start.scala.html)
• No ADRs found
• Outdated: com.datadoghq:dd-java-agent
• Outdated: com.github.tototoshi:scala-csv_3
• Outdated: com.google.inject.extensions:guice-assistedinject
• Outdated: com.google.inject:guice
• Outdated: com.rollbar:rollbar-java
• Outdated: io.swagger:swagger-parser
• Outdated: joda-time:joda-time
• Outdated: org.atteo:evo-inflector
• Outdated: org.playframework.anorm:anorm-postgres_3
• Outdated: org.playframework:play-guice_3
• Outdated: org.postgresql:postgresql
• Outdated: org.typelevel:cats-core_3
• Outdated: org.webjars:bootstrap
• Outdated: org.webjars:webjars-play_3
• Projects may be oversized for their cohesion

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

apicollective/apibuilder was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.