Introduction to Api-Interfaces
Api-Interfaces is an integral component in the communication landscape utilized by various Stability-AI projects, such as the api-bridge, api-web, and generator_server. At its core, it leverages the gRPC protocol to facilitate smooth interactions between these projects and any other client applications that need to communicate directly with api-web. This setup ensures that all parts of the ecosystem speak the same "language," thus promoting seamless integration and functionality. Developers interested in learning more about the development nuances can find comprehensive guidelines here.
Getting Started with Api-Interfaces
For individuals or organizations looking to utilize Api-Interfaces, setting up a development environment is the preliminary step.
Prerequisites
Before diving into the setup, ensure that your system meets the software requirements, which include:
- Golang: Version 1.18 or higher is necessary for Go-related development activities.
- Node.js: Your Node.js version should be at least 16.16.0, facilitating the handling of JavaScript-based processes.
- CMake: Ensure you have version 3.14 or above, which aids in project compilation.
- Protoc: This is the protocol compiler needed to compile proto source files into usable code.
- gRPC: As the backbone of Api-Interfaces communication, having gRPC installed is crucial.
To streamline your git operations with Api-Interfaces, it is advisable to clone repositories using SSH, particularly for git and go get commands. You can configure your .gitconfig file to default to SSH when interacting with GitHub, ensuring more secure and efficient cloning processes.
Setup and Building
Once equipped with the necessary tools, setting up Api-Interfaces involves a few straightforward steps:
- Clone the repository via SSH:
git clone --recurse-submodules [email protected]:Stability-AI/api-interfaces.git - Navigate into the repository:
cd api-interfaces - Initialize the project using CMake:
cmake . cmake --build .
This method compiles the project, producing files across different programming languages to support the proto files found in the src directory. It's noteworthy to clean the build environment before rebuilding to avoid inconsistency in file regeneration.
Usage of Api-Interfaces
The files generated by Api-Interfaces are placed in the gooseai directory, and their utility varies based on the programming language in use. Different files serve distinct purposes for clients and servers, as illustrated in the table below:
| Suffix | Client | Server |
|---|---|---|
| _grpc_pb | ✔️1 | ✔️ |
| _pb_service | ✔️2 | |
| _pb | ✔️ | ✔️ |
Note: Typescript/JavaScript clients only require certain files, as indicated above.
Using Api-Interfaces in Various Programming Languages
Golang
In Go, the interfaces can be incorporated into projects like any typical module. Developers can add them using:
go get github.com/Stability-AI/api-interfaces@latest
Updating involves repeating the same command with the desired version's SHA. This way, they can be seamlessly integrated into Go projects.
Python
Python developers can benefit from adding Api-Interfaces as a git submodule to their projects. Utilizing SSH for cloning the submodule is recommended. Updates can be managed by checking out newer versions within the submodule, ensuring the files remain accessible via the Python path.
Typescript / JavaScript
Similar to Python, integrating these interfaces into TypeScript or JavaScript projects is best achieved through git submodules. One must ensure that both TypeScript and JavaScript files are within reach of their respective projects.
Custom Builds and Other Languages
For users wishing to build Api-Interfaces on their own terms, it's vital to set the proto include paths correctly. These paths include:
src/protosrc/tensorizer/proto
By following these guidelines, developers can tailor the build process to fit their specific needs and environments.