Registry / web-framework / pixl-server-api

pixl-server-api

JSON →
library1.0.9jsnpmunverified

pixl-server-api is a specialized component designed for the `pixl-server` framework, enabling the creation of JSON REST APIs. Built on `pixl-server-web`, it facilitates defining API methods or entire classes that respond to configurable URL patterns such as `/api/METHOD_NAME` or `/api/NAMESPACE/METHOD_NAME`. The package is currently at version 1.0.9, indicating a stable release. While no explicit release cadence is mentioned, the `pixl-server` ecosystem tends towards stability with infrequent, targeted updates rather than rapid iteration. Its primary differentiator is its seamless integration and low-boilerplate approach within the `pixl-server` architecture, making it suitable for applications already leveraging that foundation. It focuses on straightforward JSON response handling.

web-frameworkhttp-networkingserialization
npm install pixl-server-api
github ↗package ↗
INSTALL
IMPORT
SIG · PIXL-SERVER-API
P
pixl-server-api
web-frameworkjavascriptv1.0.9
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pixl-server-api
✓ const APIComponent = require('pixl-server-api');
✗ import APIComponent from 'pixl-server-api';
This package is CommonJS-only and must be imported using `require()`.
API
✓ server.API.addHandler(...);
✗ server.api.addHandler(...);
The API component is accessed via the `API` property (uppercase) on the `PixlServer` instance, matching its configuration key.
addHandler
✓ server.API.addHandler('my_method', function(args, callback) { ... });
✗ const { addHandler } = require('pixl-server-api');
The `addHandler` method is available on the instantiated `API` component after server startup, not directly exportable from the module.

This example demonstrates how to set up a `pixl-server` with `pixl-server-api` to expose a simple `/api/add_user` endpoint, handling request arguments and sending JSON responses, including a simulated error case.

const PixlServer = require('pixl-server'); const path = require('path'); const server = new PixlServer({ __name: 'MyApiServer', __version: "1.0", config: { log_dir: path.join(__dirname, 'logs'), debug_level: 9, WebServer: { http_port: 8080, http_htdocs_dir: path.join(__dirname, 'www') }, API: { base_uri: '/api' } }, components: [ require('pixl-server-web'), require('pixl-server-api') ] }); server.startup(function() { console.log('Server started on port 8080. Try GET http://localhost:8080/api/add_user'); server.API.addHandler('add_user', function(args, callback) { console.log('Received add_user API call with args:', args); // Simulate an asynchronous operation setTimeout(() => { const username = args.username || 'guest'; if (username === 'error') { callback({ code: 1, description: "Username 'error' is not allowed." }); } else { callback({ code: 0, description: `User '${username}' added successfully!`, data: { id: Date.now(), username: username } }); } }, 100); }); // Example: Shut down the server after a period for demonstration setTimeout(() => { console.log('Shutting down server.'); server.shutdown(); }, 10000); });
Debug
Known issues
gotchaEnsure `pixl-server`, `pixl-server-web`, and `pixl-server-api` are all installed via npm, as `pixl-server-api` relies on them as core components within the `pixl-server` framework. Forgetting to install or include `pixl-server` or `pixl-server-web` will lead to runtime errors.
fix
Run `npm install pixl-server pixl-server-web pixl-server-api` to ensure all necessary dependencies are available.
affects: >=1.0.0
gotchaThe component's configuration key and access property on the `PixlServer` instance is strictly `API` (uppercase). Using `api` (lowercase) or any other variation will result in the component not being loaded or accessible, leading to `TypeError`s.
fix
Ensure configuration uses the `API` key (e.g., `config: { 'API': {...} }`) and component access uses `server.API`.
affects: >=1.0.0
gotchaAPI handlers must explicitly call the provided `callback` function with an object as an argument to send a response to the client. Failure to invoke the callback will leave the client request hanging and eventually time out.
fix
Always invoke `callback(responseObject)` at the end of your handler logic. Standard practice is `callback({ code: 0, description: 'Success!' })` or an error object with a non-zero `code`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'addHandler')
The `API` component was not properly initialized or added to the `PixlServer` instance's `components` array, or accessed with the wrong case (`server.api` instead of `server.API`).
fix
Verify that `require('pixl-server-api')` is included in the `components` array during `PixlServer` instantiation and that it's accessed as `server.API`.
Error: Cannot find module 'pixl-server-api'
The `pixl-server-api` package has not been installed in the project's `node_modules`.
fix
Run `npm install pixl-server-api` in your project directory. Ensure all `pixl-server` ecosystem dependencies (`pixl-server`, `pixl-server-web`, `pixl-server-api`) are installed.
Client request hangs indefinitely or times out when calling an API endpoint.
An API handler function failed to invoke the `callback` function, preventing a response from being sent to the client.
fix
Review your API handler logic to ensure that every possible execution path correctly calls the `callback(responseObject)` function.
Upgrade
Version history
1.0.9latest on npm
Audit
Dependencies
pixl-serverrequiredCore server framework that pixl-server-api integrates with as a component.
pixl-server-webrequiredProvides the underlying web server capabilities that pixl-server-api builds upon.
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/jhuckaby/pixl-server-api ↗
packagehttps://www.npmjs.com/package/pixl-server-api ↗
pixl-server-api — npm install pixl-server-api · libregistry