Introduction

What are Interfaces?

In Antelopejs, interfaces define contracts between different parts of the application. They specify what functions and services are available without dictating how they're implemented. This separation allows for:

• Loose coupling: Modules depend on interface contracts, not specific implementations
• Modularity: Components can be replaced or upgraded without affecting the rest of the system
• Testability: Interfaces facilitate mocking and testing in isolation
• Flexibility: Multiple implementations of the same interface can coexist

Interface Versioning

When importing interfaces, you specify both the name and version (e.g., api@dev). This allows:

• Using multiple versions of the same interface simultaneously
• Gradually migrating from older to newer versions
• Maintaining backward compatibility

We generally use the following version naming conventions:

• dev: Used when the interface is still in development and changes frequently
• beta: Applied when the interface needs approval and will likely be published in an official version soon
• 1, 2, etc.: Official stable versions used in production environments

Official versions (1, 2, etc.) are immutable once published. To evolve an interface, you must first create a new dev or beta version before releasing the next official version. This ensures stability for production code while allowing for continued development.

For example, you could use both stable and development versions of the API:

import { Controller as StableController } from "@ajs/api/1";
import { Controller as DevController } from "@ajs/api/beta";

// Use stable API for production features
class StableApiController extends StableController("/api/v1") {
  // Production-ready endpoints
}

// Use development API for experimental features
class DevApiController extends DevController("/api/beta") {
  // New features still in development
}

This versioning approach gives you the flexibility to evolve your interfaces over time while ensuring existing modules continue to work with the versions they were designed for.

Version Migration Example

// Using version 1
import { getUser } from "@ajs/users/1";

// Later migrating to version 2 which adds more features
import { getUser, searchUsers } from "@ajs/users/2";