|
| 1 | +# Zinit JSON-RPC API Documentation |
| 2 | + |
| 3 | +This document describes the JSON-RPC 2.0 API for Zinit. The API allows external applications to control and query Zinit services using the JSON-RPC 2.0 protocol. |
| 4 | + |
| 5 | +> **Note:** The JSON-RPC API is currently in development and may not be fully functional in all Zinit versions. For production use, it's recommended to use the [line-based protocol](protocol.md) which is stable and well-tested. |
| 6 | +
|
| 7 | +## OpenRPC Specification |
| 8 | + |
| 9 | +The OpenRPC specification for Zinit's API is exists in the [openrpc.json](../../openrpc.json) file. You can copy this JSON and paste it into the [OpenRPC Playground](https://playground.open-rpc.org/) to explore the API interactively. |
| 10 | + |
| 11 | + |
| 12 | +## Using the OpenRPC Playground |
| 13 | + |
| 14 | +To explore the Zinit JSON-RPC API interactively: |
| 15 | + |
| 16 | +1. Visit [OpenRPC Playground](https://playground.open-rpc.org/) |
| 17 | +2. Copy the JSON specification above |
| 18 | +3. Paste it into the editor on the left side of the playground |
| 19 | +4. Use the interactive documentation on the right side to explore the API |
| 20 | + |
| 21 | +## JSON-RPC 2.0 Protocol |
| 22 | + |
| 23 | +Zinit implements the JSON-RPC 2.0 protocol as defined in the [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification). |
| 24 | + |
| 25 | +### Request Format |
| 26 | + |
| 27 | +```json |
| 28 | +{ |
| 29 | + "jsonrpc": "2.0", |
| 30 | + "id": 1, |
| 31 | + "method": "service.list", |
| 32 | + "params": {} |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +Where: |
| 37 | +- `jsonrpc`: Must be exactly "2.0" |
| 38 | +- `id`: A unique identifier for the request (can be a number, string, or null) |
| 39 | +- `method`: The name of the method to call |
| 40 | +- `params`: An object containing the parameters for the method (can be omitted for methods that don't require parameters) |
| 41 | + |
| 42 | +### Response Format |
| 43 | + |
| 44 | +```json |
| 45 | +{ |
| 46 | + "jsonrpc": "2.0", |
| 47 | + "id": 1, |
| 48 | + "result": {} |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +Or, in case of an error: |
| 53 | + |
| 54 | +```json |
| 55 | +{ |
| 56 | + "jsonrpc": "2.0", |
| 57 | + "id": 1, |
| 58 | + "error": { |
| 59 | + "code": -32000, |
| 60 | + "message": "Service not found", |
| 61 | + "data": "service name \"unknown\" unknown" |
| 62 | + } |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +Where: |
| 67 | +- `jsonrpc`: Always "2.0" |
| 68 | +- `id`: The same id as in the request |
| 69 | +- `result`: The result of the method call (only present if the call was successful) |
| 70 | +- `error`: Error information (only present if the call failed) |
| 71 | + - `code`: A number indicating the error type |
| 72 | + - `message`: A short description of the error |
| 73 | + - `data`: Additional information about the error (optional) |
| 74 | + |
| 75 | +## Client Example: Using Python |
| 76 | + |
| 77 | +A simple Python client for the JSON-RPC API (note that this may not work with all Zinit versions): |
| 78 | + |
| 79 | +```python |
| 80 | +import socket |
| 81 | +import json |
| 82 | + |
| 83 | +def zinit_jsonrpc(method, params=None): |
| 84 | + sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) |
| 85 | + sock.connect("/var/run/zinit.sock") |
| 86 | + |
| 87 | + request = { |
| 88 | + "jsonrpc": "2.0", |
| 89 | + "id": 1, |
| 90 | + "method": method |
| 91 | + } |
| 92 | + |
| 93 | + if params: |
| 94 | + request["params"] = params |
| 95 | + |
| 96 | + # Send the JSON-RPC request without a newline |
| 97 | + sock.send(json.dumps(request).encode()) |
| 98 | + |
| 99 | + response = sock.recv(4096).decode() |
| 100 | + sock.close() |
| 101 | + |
| 102 | + return json.loads(response) |
| 103 | + |
| 104 | +# Usage examples |
| 105 | +services = zinit_jsonrpc("service.list") |
| 106 | +redis_status = zinit_jsonrpc("service.status", {"name": "redis"}) |
| 107 | +start_result = zinit_jsonrpc("service.start", {"name": "nginx"}) |
| 108 | +``` |
| 109 | + |
| 110 | +## Error Codes |
| 111 | + |
| 112 | +Zinit uses standard JSON-RPC 2.0 error codes as well as custom error codes: |
| 113 | + |
| 114 | +### Standard JSON-RPC 2.0 Error Codes |
| 115 | + |
| 116 | +- `-32600`: Invalid Request - The JSON sent is not a valid Request object |
| 117 | +- `-32601`: Method not found - The method does not exist / is not available |
| 118 | +- `-32602`: Invalid params - Invalid method parameter(s) |
| 119 | +- `-32603`: Internal error - Internal JSON-RPC error |
| 120 | + |
| 121 | +### Custom Zinit Error Codes |
| 122 | + |
| 123 | +- `-32000`: Service not found - The requested service does not exist |
| 124 | +- `-32001`: Service already monitored - The service is already being monitored |
| 125 | +- `-32002`: Service is up - The service is currently running |
| 126 | +- `-32003`: Service is down - The service is currently not running |
| 127 | +- `-32004`: Invalid signal - The provided signal is invalid |
| 128 | +- `-32005`: Config error - Error in service configuration |
| 129 | +- `-32006`: Shutting down - The system is already shutting down |
0 commit comments