How aalyria/api works
Project Type and Purpose
• The repository is primarily focused on providing Spacetime’s network APIs, which are organized into three main interfaces: the Northbound Interface (NBI), Southbound Interface (SBI), and Federation (East-West) API.
• It also includes an SBI agent implemented in Go (contained in the “agent” directory) that interacts with network devices, and there are sections for API definitions (gRPC/Protobufs in the “api” directory) and sample implementations or clients (Java and Python in their respective folders).
• The overall design enables orchestration and real-time control of network elements and interconnection among networks.
Analyzing the File Structure
• Top-Level Architecture: The project is modularized into multiple directories:
• “api” – Contains the gRPC and Protocol Buffers definitions for various API components (NBI, scheduling, federation, provisioning, telemetry, etc.).
• “agent” – Holds the code for the SBI agent in Go and includes several subdirectories that reflect modular internal components (like “internal”, “telemetry”, “enactment”, etc.) which are partitioned for tasks such as logging, task management, external process handling, and networking.
• “auth”, “java”, “py” – These directories indicate additional authentication components and language-specific sample implementations.
• “contrib” and “entity_samples” – These directories offer open-source contributions or tutorial examples, providing real-world scenario setups that may help users in building their own network scenarios.
• Supporting files such as Bazel configuration, tests, build scripts, and governance documents are also present, giving hints about how the project is built and deployed.
Key Components and Their Relationships
• APIs (Northbound, Southbound, Federation):
• The “api” directory is the central definition place for all API communications (including common messages, models, scheduling, telemetry, etc.). These definitions unify the interaction between the system’s internal components and external entities.
• SBI Agent:
• Found in the “agent” directory, this Go-based service likely implements communication with network devices. It contains further subdivisions for telemetry, enactment, external processes, and channel communications. Internally, it also integrates modules for configuration (e.g., configpb) and networking (e.g., netlink) supporting both operational logic and testing.
• Authentication and Client Implementations:
• The “auth” directory (and analogous directories for Java and Python) implement the authentication mechanisms (JWT management, call credentials) needed to secure access to the APIs.
• Developer Tools & Helpers:
• Tools like “nbictl” and other scripts (as in the “tools” directory) help with provisioning, testing, and simulation of API usage.
Architectural Patterns and Design Principles
• Modularity: The directory structure clearly shows a modular design, where API definitions, agent functionalities, and authentication are separated.
• Microservice/Service-Oriented Approach: While the project is distributed across multiple languages and components, each major functional area (e.g., API definitions vs. the SBI agent) can be seen as a service or module that interacts over well-defined interfaces (gRPC, Protocol Buffers).
• Separation of Concerns: The internal subdivisions (e.g., “telemetry”, “enactment”, “auth”) ensure that different aspects of the system—data collection, network control, and permission management—are clearly delineated.