Skip to main content

API Specifications Overview

Overview​

The specification catalog contains organization-wide API specifications that establish standardized communication patterns between applications across the RELEX platform. These specifications serve as foundational contracts that applications implement to ensure consistent interoperability.

Understanding API Specifications​

API specifications define standard interfaces for common operations between RELEX platform applications. For example, our batch process and job notification specification establishes a contract for triggering asynchronous jobs across applications, monitoring their execution status, and receiving final results.

Key Concepts​

Common Language​

API specifications create a shared vocabulary and set of expectations between applications, making it easier to implement cross-application operations consistently.

Implementation Format​

All specifications are represented as JSON Schema, which was chosen as the standard specification type across RELEX.

Abstract Base Schemas​

The API specifications themselves are abstract base schemas that applications build upon. No application implements the base schemas directly. Instead, each application adapts the base schema to create application-specific schemas. Base schemas include intentional extension points, where properties are defined as generic "objects" that applications can customize according to their needs.

Application-Specific Schemas​

When implementing an API specification, applications create their own specialized version of the base schema. These application-specific schemas must remain valid against the abstract base schema while incorporating their unique requirements. All specialized schemas can be found in the API catalog for reference.

Versioning​

All API specifications follow semantic versioning (SemVer) to manage changes and maintain compatibility across the platform.

Schema Validation​

During development and integration, it's crucial to validate application-specific schemas against their base specifications. This ensures backwards compatibility and prevents unintended breaking changes. We recommend validating schemas both during development and as part of the CI/CD pipeline.

Best Practices​

When extending base schemas, applications should follow these principles:

  • Only extend at designated extension points to maintain consistency
  • Document any application-specific extensions thoroughly
  • Consider backwards compatibility when making changes
  • Reuse existing patterns when possible instead of creating new ones

Getting Started​

New applications looking to implement an API specification should:

  1. Review the relevant base schema in the specification catalog
  2. Identify which extension points are needed for their use case
  3. Create their application-specific schema. See README.md for detailed instructions.
  4. Implement the contract according to their schema
  5. Add their schema to the API catalog

Governance​

API specifications are maintained by the Internal Integrations Special Interest Group (II-SIG), with Matias Käkelä serving as the main point of contact for technical matters.

Making Changes​

If you need to modify an existing specification or create a new one, start by reaching out to the II-SIG through Slack. The group can provide guidance on:

  • Whether your needs can be met by existing specifications
  • The best approach to extend or create specifications
  • Technical considerations and potential impacts
  • Implementation patterns and best practices

While there isn't a formal process for changes, early consultation with II-SIG helps ensure that new specifications or modifications align with platform-wide integration patterns and meet cross-application needs effectively.

Creating New Specifications​

When considering a new base specification, discuss your use case with II-SIG. While there are no formal criteria, common considerations include:

  • Whether the integration pattern could be useful for other applications
  • How it fits with existing specifications
  • The potential for reuse across the platform
  • Maintenance and support implications