0
# HTTP Registry API
1

2
RESTful API implementing npm registry protocol for package publishing, installation, and management. The HTTP API provides all standard npm registry operations plus Verdaccio-specific features.
3

4
## Capabilities
5

6
### Package Management
7

8
Core package CRUD operations following npm registry protocol.
9

10
```typescript { .api }
11
// Package metadata retrieval
12
app.get('/:package', packageHandler);
13
app.get('/:package/:version', packageVersionHandler);
14

15
// Package publishing and updates
16
app.put('/:package/:_rev?/:revision?', publishHandler);
17
app.put('/:package/-rev/:revision', updatePackageHandler);
18

19
// Package deletion
20
app.delete('/:package/-rev/*', unpublishHandler);
21
app.delete('/:package/-/:filename/-rev/:revision', removeTarballHandler);
22

23
// Tarball operations
24
app.get('/:package/-/:filename', downloadTarballHandler);
25
app.put('/:package/-/:filename/*', uploadPackageTarballHandler);
26

27
// Debug endpoints (development only)
28
app.put('/:package/:version/-tag/:tag', addVersionHandler);
29
```
30

31
**Usage Examples:**
32

33
```bash
34
# Get package metadata
35
curl http://localhost:4873/express
36

37
# Get specific version
38
curl http://localhost:4873/express/4.18.2
39

40
# Publish package (requires authentication)
41
npm publish --registry http://localhost:4873
42

43
# Download tarball
44
curl http://localhost:4873/express/-/express-4.18.2.tgz
45
```
46

47
### User Management & Authentication
48

49
User registration, authentication, and profile management.
50

51
```typescript { .api }
52
// User authentication
53
app.put('/-/user/:user', userHandler);
54
app.post('/-/user/:user', userLoginHandler);
55

56
// Current user info
57
app.get('/-/whoami', whoamiHandler);
58

59
// User profile (v1 API)
60
app.get('/-/npm/v1/user', profileHandler);
61
app.post('/-/npm/v1/user', updateProfileHandler);
62

63
// Token management (v1 API)
64
app.post('/-/npm/v1/tokens', createTokenHandler);
65
app.get('/-/npm/v1/tokens', listTokensHandler);
66
app.delete('/-/npm/v1/tokens/token/:tokenKey', deleteTokenHandler);
67
```
68

69
**Usage Examples:**
70

71
```bash
72
# Create user / login
73
npm adduser --registry http://localhost:4873
74

75
# Check current user
76
npm whoami --registry http://localhost:4873
77

78
# Create authentication token
79
curl -X POST http://localhost:4873/-/npm/v1/tokens \
80
  -H "Authorization: Bearer <token>" \
81
  -H "Content-Type: application/json" \
82
  -d '{"password":"<password>","readonly":false,"cidr_whitelist":[]}'
83
```
84

85
### Distribution Tags
86

87
Package version tag management (latest, beta, alpha, etc.).
88

89
```typescript { .api }
90
// Get all dist-tags for package
91
app.get('/-/package/:package/dist-tags', distTagsListHandler);
92

93
// Get specific dist-tag version
94
app.get('/:package/:tag', distTagHandler);
95

96
// Update/create dist-tag
97
app.put('/-/package/:package/dist-tags/:tag', tagPackageVersionHandler);
98
app.post('/-/package/:package/dist-tags/:tag', tagPackageVersionHandler);
99
app.post('/-/package/:package/dist-tags', updateMultipleTagsHandler);
100

101
// Delete dist-tag
102
app.delete('/-/package/:package/dist-tags/:tag', deleteDistTagHandler);
103
```
104

105
**Usage Examples:**
106

107
```bash
108
# Get all tags for package
109
curl http://localhost:4873/express/-/tags
110

111
# Set dist-tag
112
npm dist-tag add express@4.18.2 stable --registry http://localhost:4873
113

114
# Remove dist-tag
115
npm dist-tag rm express stable --registry http://localhost:4873
116
```
117

118
### Search & Discovery
119

120
Package search and discovery functionality.
121

122
```typescript { .api }
123
// Legacy search (deprecated)
124
app.get('/-/all', allPackagesHandler);
125
app.get('/-/all/since', allPackagesSinceHandler);
126

127
// Modern search (v1 API)
128
app.get('/-/v1/search', searchHandler);
129

130
// Package stars/favorites
131
app.get('/-/_view/starredByUser', starredByUserHandler);
132
app.put('/:package/-/_star', starPackageHandler);
133
app.delete('/:package/-/_star', unstarPackageHandler);
134
```
135

136
**Usage Examples:**
137

138
```bash
139
# Search packages
140
curl "http://localhost:4873/-/v1/search?text=express&size=20"
141

142
# Get all packages
143
curl http://localhost:4873/-/all
144

145
# Star a package
146
curl -X PUT http://localhost:4873/express/-/_star \
147
  -H "Authorization: Bearer <token>"
148
```
149

150
### System Operations
151

152
Health checks and system status information.
153

154
```typescript { .api }
155
// Health check / ping
156
app.get('/-/ping', pingHandler);
157

158
// Current user info
159
app.get('/-/whoami', whoamiHandler);
160
```
161

162
### NPM v1 Profile API
163

164
Modern npm profile management endpoints.
165

166
```typescript { .api }
167
// Get user profile
168
app.get('/-/npm/v1/user', profileHandler);
169

170
// Update user profile
171
app.post('/-/npm/v1/user', updateProfileHandler);
172
```
173

174
### NPM v1 Token Management
175

176
Authentication token management for modern npm clients.
177

178
```typescript { .api }
179
// List user tokens
180
app.get('/-/npm/v1/tokens', listTokensHandler);
181

182
// Create new token
183
app.post('/-/npm/v1/tokens', createTokenHandler);
184

185
// Delete specific token
186
app.delete('/-/npm/v1/tokens/token/:tokenKey', deleteTokenHandler);
187
```
188

189
### Web UI API
190

191
Verdaccio web interface endpoints for package browsing and management.
192

193
```typescript { .api }
194
// Web UI package management
195
app.get('/-/verdaccio/data/packages', webPackageListHandler);
196
app.get('/-/verdaccio/data/sidebar/:scope/:package', webSidebarHandler);
197
app.get('/-/verdaccio/data/sidebar/:package', webSidebarHandler);
198
app.get('/-/verdaccio/data/readme/:scope/:package/:version', webReadmeHandler);
199
app.get('/-/verdaccio/data/readme/:package/:version', webReadmeHandler);
200

201
// Web UI search
202
app.get('/-/verdaccio/data/search/:anything', webSearchHandler);
203

204
// Web UI authentication
205
app.post('/-/verdaccio/sec/login', webLoginHandler);
206
app.put('/-/verdaccio/sec/reset_password', webPasswordResetHandler);
207

208
// Static assets
209
app.get('/-/static/favicon.ico', serveFaviconHandler);
210
```
211

212
**Usage Examples:**
213

214
```bash
215
# Health check
216
curl http://localhost:4873/-/ping
217

218
# Check current user
219
curl http://localhost:4873/-/whoami
220

221
# Get package list for web UI
222
curl http://localhost:4873/-/verdaccio/data/packages
223
```
224

225
## Authentication
226

227
The API supports multiple authentication methods:
228

229
### Bearer Token Authentication
230
```bash
231
curl -H "Authorization: Bearer <token>" http://localhost:4873/package
232
```
233

234
### Basic Authentication
235
```bash
236
curl -u username:password http://localhost:4873/package
237
```
238

239
### JWT Middleware
240
Internal JWT middleware for session management and token validation.
241

242
## Request/Response Format
243

244
### Standard Headers
245
- `Content-Type: application/json` for JSON payloads
246
- `User-Agent: npm/<version>` for npm client compatibility
247
- `Authorization: Bearer <token>` for authenticated requests
248

249
### Error Responses
250
```typescript { .api }
251
interface ErrorResponse {
252
  error: string;
253
  reason?: string;
254
}
255
```
256

257
Common HTTP status codes:
258
- `200`: Success
259
- `201`: Created (package published)
260
- `400`: Bad Request (invalid data)
261
- `401`: Unauthorized (authentication required)
262
- `403`: Forbidden (insufficient permissions)
263
- `404`: Not Found (package/version doesn't exist)
264
- `409`: Conflict (package already exists)
265
- `500`: Internal Server Error
266

267
### Package Metadata Format
268
```typescript { .api }
269
interface PackageMetadata {
270
  _id: string;
271
  name: string;
272
  description?: string;
273
  "dist-tags": { [tag: string]: string };
274
  versions: { [version: string]: VersionMetadata };
275
  time: { [version: string]: string };
276
  author?: Person;
277
  contributors?: Person[];
278
  repository?: Repository;
279
  keywords?: string[];
280
  license?: string;
281
}
282

283
interface VersionMetadata {
284
  name: string;
285
  version: string;
286
  description?: string;
287
  main?: string;
288
  types?: string;
289
  dependencies?: Dependencies;
290
  devDependencies?: Dependencies;
291
  peerDependencies?: Dependencies;
292
  dist: {
293
    tarball: string;
294
    shasum: string;
295
    integrity?: string;
296
  };
297
}
298
```
299

300
## Rate Limiting
301

302
Verdaccio supports configurable rate limiting for API endpoints:
303
- Per-IP request limits
304
- Authentication-based limits
305
- Configurable time windows
306

307
## CORS Support
308

309
Cross-Origin Resource Sharing (CORS) is enabled by default for web interface compatibility.
310

311
## Proxy Behavior
312

313
When packages are not found locally, Verdaccio can proxy requests to upstream registries based on configuration:
314
- Transparent proxying to npmjs.org or other registries
315
- Caching of downloaded packages
316
- Fallback behavior for missing packages