Skip to content

Commit 52dbcf8

Browse files
geroplgeropl
committed
[memory-bank] add public-api doc
1 parent 60c4a33 commit 52dbcf8

File tree

2 files changed

+192
-0
lines changed

2 files changed

+192
-0
lines changed

‎memory-bank/components.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ This file serves as index for the per-component documentation in individual md f
1616
- [ide-service-api](components/ide-service-api.md)
1717
- [ide-metrics-api](components/ide-metrics-api.md)
1818
- [ws-manager-bridge-api](components/ws-manager-bridge-api.md)
19+
- [public-api](components/public-api.md)
1920
- [usage-api](components/usage-api.md)
2021
- [local-app-api](components/local-app-api.md)
2122
- [dashboard](components/dashboard.md)

‎memory-bank/components/public-api.md

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Public API
2+
3+
## Overview
4+
The Public API defines the gRPC interfaces for programmatic access to Gitpod functionality. It serves as the canonical way for external integrations, automation, and third-party tools to interact with Gitpod's core services. The API is structured into two packages (stable and experimental) with different compatibility guarantees and is designed to be backward compatible, well-documented, and follow modern API design principles.
5+
6+
## Purpose
7+
This API provides a standardized interface for:
8+
- Programmatically managing workspaces (create, start, stop, delete)
9+
- Accessing and managing user information
10+
- Working with organizations and teams
11+
- Managing projects and repositories
12+
- Integrating with source code management systems
13+
- Configuring editors and IDEs
14+
- Authenticating via OpenID Connect
15+
- Managing personal access tokens
16+
- Automating Gitpod workflows
17+
18+
## Architecture
19+
The Public API is implemented as a set of gRPC services defined in Protocol Buffer files. These definitions are used to generate client and server code in Go, TypeScript, and Java. The API is exposed on `api.gitpod.io` or `api.<domain>` for Dedicated installations.
20+
21+
The API is structured into two main packages:
22+
23+
1. **Stable (v1)**:
24+
- Located in `gitpod/v1/`
25+
- Provides compatibility guarantees
26+
- Services, calls, types, and fields are not removed without following a deprecation policy
27+
- Services, calls, types, and fields are not renamed
28+
- Non-successful responses are described exhaustively
29+
- **Implementation**: Directly implemented in the server component using Connect
30+
31+
2. **Experimental**:
32+
- Located in `gitpod/experimental/v1/`
33+
- Provides no compatibility guarantees
34+
- May change frequently
35+
- **Implementation**: Handled in the public-api-server component, and either:
36+
- Implemented directly in Go
37+
- Forwarded to the old websocket API in the server component
38+
39+
## Implementation Patterns
40+
41+
### Stable API Implementation
42+
The stable API (v1) is implemented directly in the server component using Connect. This means:
43+
- The server component handles the business logic for these API endpoints
44+
- The implementation is in TypeScript using Connect
45+
46+
### Experimental API Implementation
47+
The experimental API is handled in the public-api-server component in two ways:
48+
49+
1. **Direct Implementation**:
50+
- Some services are implemented directly in Go within the public-api-server
51+
- These implementations handle the business logic directly
52+
- They may interact with the database or other services directly
53+
54+
2. **Forwarded Implementation**:
55+
- Other services forward requests to the old websocket API in the server component
56+
- The public-api-server acts as a proxy, translating gRPC requests to websocket API calls
57+
- The server component handles the actual business logic
58+
- This approach is often used for functionality that already exists in the server component
59+
60+
## Key Services
61+
62+
### Stable API (v1)
63+
All implemented in server component using Connect:
64+
- WorkspaceService
65+
- OrganizationService
66+
- UserService
67+
- TokenService
68+
- SCMService
69+
- AuthProviderService
70+
- ConfigurationService
71+
- EnvVarService
72+
- InstallationService
73+
- PrebuildService
74+
- SSHService
75+
- VerificationService
76+
77+
### Experimental API
78+
Implemented in public-api-server:
79+
- WorkspacesService (Forwarded to server)
80+
- TeamsService (Directly implemented in Go)
81+
- ProjectsService (Forwarded to server)
82+
- EditorService (Directly implemented in Go)
83+
- IDEClientService (Directly implemented in Go)
84+
- OIDCService (Directly implemented in Go)
85+
- IdentityProviderService (Directly implemented in Go)
86+
- TokensService (Forwarded to server)
87+
- UserService (Forwarded to server)
88+
- StatsService (Directly implemented in Go)
89+
90+
## Communication Patterns
91+
- The API uses gRPC for efficient, typed communication
92+
- Connect is used for the stable API implementation
93+
- Requests include authentication tokens for identifying the user
94+
- Pagination is supported for listing operations
95+
- Streaming is used for real-time updates (e.g., workspace status changes)
96+
- Field masks are used to specify which fields to return or update
97+
98+
### Implementation-specific Patterns
99+
- **Stable API (v1)**:
100+
- Requests are handled by the server component using Connect
101+
- The public-api-server routes requests to the server component
102+
103+
- **Experimental API**:
104+
- Directly implemented services handle requests in the public-api-server
105+
- Forwarded services translate gRPC requests to websocket API calls to the server component
106+
107+
## Dependencies
108+
- **Server Component**: Implements the stable API and handles forwarded experimental API requests
109+
- **Public-api-server Component**: Implements experimental APIs directly or forwards to server
110+
- **Database**: Stores user, workspace, and organization data
111+
- **Redis**: Used for caching and session management
112+
- **gRPC and Connect**: Used for API implementation
113+
- **Protocol Buffers**: Used for API definition and code generation
114+
115+
## Usage Examples
116+
- Creating and managing workspaces programmatically
117+
- Building custom dashboards and management tools
118+
- Integrating Gitpod with CI/CD pipelines
119+
- Automating workspace provisioning
120+
- Building IDE extensions that interact with Gitpod
121+
- Implementing custom authentication flows
122+
- Integrating with third-party services
123+
124+
## Version Compatibility
125+
The API uses Protocol Buffers version 3 (proto3) syntax, which provides forward and backward compatibility features.
126+
127+
### Stable API (v1)
128+
- Services, calls, types, and fields are not removed without following a deprecation policy
129+
- Services, calls, types, and fields are not renamed
130+
- Non-successful responses are described exhaustively
131+
- Changes require an API User Experience review
132+
133+
### Experimental API
134+
- No compatibility guarantees
135+
- May change frequently
136+
- Should not be relied upon for production use
137+
138+
## Code Generation and Building
139+
140+
### Regenerating Code from Protobuf Definitions
141+
The Public API uses Protocol Buffers and gRPC for defining interfaces. When changes are made to the `.proto` files, the corresponding code in Go, TypeScript, and Java needs to be regenerated.
142+
143+
To regenerate the code:
144+
145+
1. Navigate to the public-api directory:
146+
```bash
147+
cd components/public-api
148+
```
149+
150+
2. Run the generate script:
151+
```bash
152+
./generate.sh
153+
```
154+
155+
3. Rebuild the typescript code:
156+
```bash
157+
cd typescript-commond && yarn build
158+
```
159+
160+
This script performs the following actions:
161+
- Installs necessary dependencies
162+
- Lints the proto files using buf
163+
- Runs breaking change detection against the main branch
164+
- Removes previously generated files
165+
- Generates Go, TypeScript, and Java code using buf
166+
- Updates license headers
167+
- Runs formatting tools
168+
- Builds the TypeScript package
169+
170+
### Building After Code Generation
171+
After regenerating the code, you may need to rebuild components that depend on the Public API. This typically involves:
172+
173+
1. For Go components:
174+
```bash
175+
cd <component-directory>
176+
go build ./...
177+
```
178+
179+
2. For TypeScript components:
180+
```bash
181+
cd <component-directory>
182+
yarn install
183+
yarn build
184+
```
185+
186+
3. Using Leeway (for CI/CD):
187+
```bash
188+
leeway build -D components/<component-name>:app
189+
```
190+
191+
The Public API is a critical component for enabling programmatic access to Gitpod functionality. It enables third-party integrations, automation, and custom tooling to interact with Gitpod in a standardized, versioned way.

0 commit comments

Comments
 (0)