Knowledge base

Information about vpsFree.org, manuals and FAQs.

User Tools

Site Tools

You are here: vpsFree.org knowledge base » manuals » vps » API
Trace:
manuals:vps:api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
manuals:vps:api [2026/11/01 19:48] – Organize authentication and CLI usage and update installation and Ruby examples aithermanuals:vps:api [2026/11/01 19:49] (current) – Add a client overview and complete examples for PHP, Python, JavaScript, TypeScript, Go and Rust aither
Line 17: Line 17:
  
 ===== Working with the API ===== ===== Working with the API =====
-The API is built on the [[https://github.com/vpsfreecz/haveapi|HaveAPI]] framework +The API uses the [[https://github.com/vpsfreecz/haveapi|HaveAPI]] framework. 
-which we have developed. The framework creates +Its [[https://github.com/vpsfreecz/haveapi#what-is-a-self-describing-api|self-description]] 
-a [[https://github.com/vpsfreecz/haveapi#what-is-a-self-describing-api|self-describing]] +lists the available resources, actions and parameters.
-API, which means that premade generic clients can be +
-used:+
  
-  * Ruby - https://github.com/vpsfreecz/vpsfree-client +The following clients are available:
-  * PHP - https://github.com/vpsfreecz/haveapi/tree/master/clients/php +
-  * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js +
-  * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go+
  
-Usage examples can always be found in the ''README.md'' of each client. In general, the client +  * [[#installing_vpsfree-client|vpsfreectl CLI]] and [[#ruby_client|Ruby library]] from the ''vpsfree-client'' package 
-receives the API URL, then the client downloads the documentation and uses it for setup.+  * [[#php_client|PHP]] 
 +  * [[#python_client|Python]] 
 +  * [[#dynamic_haveapi_client_for_javascript_and_typescript|Dynamic HaveAPI client for JavaScript and TypeScript]] 
 +  * [[#go_client|Go]] 
 +  * [[#generated_typescript_client_for_vpsadmin|Generated TypeScript client for vpsAdmin]] 
 +  * [[#rust_client|Rust]]
  
 The API is [[wp>Representational state transfer|RESTful]], so any REST client The API is [[wp>Representational state transfer|RESTful]], so any REST client
Line 600: Line 600:
 end end
 </code> </code>
 +
 +===== Other clients =====
 +
 +Each example requests an [[#tokens|API token]] with your vpsAdmin username and
 +password, then prints the ID and hostname of up to 10 VPSes. Replace ''USERNAME''
 +and ''PASSWORD'' with your credentials. To use an existing token, replace the
 +login code with the commented alternative and fill in ''TOKEN''.
 +
 +==== PHP client ====
 +
 +Install the [[https://github.com/vpsfreecz/haveapi/tree/master/clients/php|HaveAPI PHP client]]
 +using Composer:
 +
 +<code bash>
 +composer require haveapi/client
 +</code>
 +
 +Save this example as ''vps-list.php'' next to the ''vendor'' directory and run it
 +with ''php vps-list.php'':
 +
 +<code php>
 +<?php
 +require __DIR__ . '/vendor/autoload.php';
 +
 +$api = new \HaveAPI\Client('https://api.vpsfree.cz');
 +$api->authenticate('token', ['user' => 'USERNAME', 'password' => 'PASSWORD']);
 +// Or replace the login call above with an existing token:
 +// $api->authenticate('token', ['token' => 'TOKEN']);
 +
 +foreach ($api->vps->list(['limit' => 10]) as $vps) {
 +    echo $vps->id . ': ' . $vps->hostname . PHP_EOL;
 +}
 +</code>
 +
 +See the [[https://github.com/vpsfreecz/haveapi/tree/master/clients/php#usage|client README]]
 +for other actions and error handling.
 +
 +==== Python client ====
 +
 +Install [[https://pypi.org/project/haveapi-client/|haveapi-client]] using pip:
 +
 +<code bash>
 +python -m pip install haveapi-client
 +</code>
 +
 +Save this example as ''vps-list.py'' and run it with ''python vps-list.py'':
 +
 +<code python>
 +from haveapi_client import Authenticated, Client, TokenAuth
 +
 +with Client("https://api.vpsfree.cz") as api:
 +    login = api.begin_token_login({
 +        "user": "USERNAME",
 +        "password": "PASSWORD",
 +        "lifetime": "renewable_auto",
 +    })
 +    if not isinstance(login, Authenticated):
 +        raise RuntimeError("Login requires another step")
 +    # Or replace the login block above with an existing token:
 +    # api.set_auth(TokenAuth("TOKEN"))
 +
 +    result = api.vps.list(limit=10)
 +    for vps in result.data:
 +        print(vps["id"], vps["hostname"])
 +</code>
 +
 +The [[https://github.com/vpsfreecz/haveapi/tree/master/clients/python|client README]]
 +also covers asynchronous calls with ''AsyncClient''.
 +
 +==== Dynamic HaveAPI client for JavaScript and TypeScript ====
 +
 +Both languages use the same npm package, which includes TypeScript declarations:
 +
 +<code bash>
 +npm install haveapi-client
 +</code>
 +
 +This example works in JavaScript and TypeScript. To run it with Node.js, save it
 +as ''vps-list.mjs'' and use ''node vps-list.mjs'':
 +
 +<code javascript>
 +import { AsyncClient } from "haveapi-client";
 +
 +async function main() {
 +  const api = new AsyncClient("https://api.vpsfree.cz");
 +  await api.authenticate("token", { user: "USERNAME", password: "PASSWORD" });
 +  // Or replace the login call above with an existing token:
 +  // await api.authenticate("token", { token: "TOKEN" });
 +  const result = await api.resource("vps").action("list")({
 +    params: { limit: 10 },
 +  });
 +  const vpses = result.response.data;
 +  if (Array.isArray(vpses)) {
 +    for (const vps of vpses) {
 +      console.log(vps.id, vps.hostname);
 +    }
 +  }
 +}
 +
 +main().catch(() => console.error("The API request failed."));
 +</code>
 +
 +See the [[https://github.com/vpsfreecz/haveapi/tree/master/clients/js|client README]]
 +for other actions and browser usage.
 +
 +==== Go client ====
 +
 +Add the [[https://github.com/vpsfreecz/vpsadmin-go-client|vpsAdmin Go client]]
 +to your Go module:
 +
 +<code bash>
 +go get github.com/vpsfreecz/vpsadmin-go-client/client
 +</code>
 +
 +Save this example as ''main.go'' and run it with ''go run .'':
 +
 +<code go>
 +package main
 +
 +import (
 + "fmt"
 + "log"
 +
 + "github.com/vpsfreecz/vpsadmin-go-client/client"
 +)
 +
 +func main() {
 + api := client.New("https://api.vpsfree.cz")
 + if err := api.SetNewTokenAuth(&client.TokenAuthOptions{
 + User:     "USERNAME",
 + Password: "PASSWORD",
 + }); err != nil {
 + log.Fatal(err)
 + }
 + // Or replace the login block above with an existing token:
 + // api.SetExistingTokenAuth("TOKEN")
 +
 + action := api.Vps.Index.Prepare()
 + action.NewInput().SetLimit(10)
 + response, err := action.Call()
 + if err != nil {
 + log.Fatal(err)
 + }
 + if !response.Status {
 + log.Fatalf("%s: %v", response.Message, response.Errors)
 + }
 +
 + for _, vps := range response.Output {
 + fmt.Println(vps.Id, vps.Hostname)
 + }
 +}
 +</code>
 +
 +See the [[https://github.com/vpsfreecz/vpsadmin-go-client#usage|client README]]
 +for other actions and parameters.
 +
 +==== Generated TypeScript client for vpsAdmin ====
 +
 +The [[https://github.com/vpsfreecz/vpsadmin-typescript-client|vpsAdmin TypeScript client]]
 +provides typed methods for vpsAdmin resources and actions. Install it using npm,
 +which also installs its ''haveapi-client'' dependency:
 +
 +<code bash>
 +npm install vpsadmin-typescript-client
 +</code>
 +
 +This example works in JavaScript and TypeScript. To run it with Node.js, save it
 +as ''vps-list.mjs'' and use ''node vps-list.mjs''.
 +Use ''https://api.vpsfree.cz/v7.0'' as the base URL for this client:
 +
 +<code javascript>
 +import { AsyncClient } from "haveapi-client";
 +import { createHaveApiExecutor, createVpsAdminClient } from "vpsadmin-typescript-client";
 +
 +async function main() {
 +  const runtime = new AsyncClient("https://api.vpsfree.cz/v7.0");
 +  await runtime.authenticate("token", { user: "USERNAME", password: "PASSWORD" });
 +  // Or replace the login call above with an existing token:
 +  // await runtime.authenticate("token", { token: "TOKEN" });
 +  const api = createVpsAdminClient({ execute: createHaveApiExecutor(runtime) });
 +  const page = await api.vps.index({ params: { limit: 10 } });
 +  for (const vps of page.data) {
 +    console.log(vps.id, vps.hostname);
 +  }
 +}
 +
 +main().catch(() => console.error("The API request failed."));
 +</code>
 +
 +See the [[https://github.com/vpsfreecz/vpsadmin-typescript-client#readme|client README]]
 +for other actions and types.
 +
 +==== Rust client ====
 +
 +Add the [[https://crates.io/crates/vpsadmin-client|vpsadmin-client]] crate to your
 +Rust project. This example uses synchronous calls, so enable the ''blocking'' feature:
 +
 +<code bash>
 +cargo add vpsadmin-client --features blocking
 +</code>
 +
 +Save this example as ''src/main.rs'' and run it with ''cargo run'':
 +
 +<code rust>
 +use vpsadmin_client::{blocking::Client, TokenStep};
 +
 +fn main() -> Result<(), Box<dyn std::error::Error>> {
 +    let login = Client::builder("https://api.vpsfree.cz").build()?;
 +    let response = login.authentication__token__token().request()
 +        .user("USERNAME")
 +        .password("PASSWORD")
 +        .lifetime("renewable_auto")
 +        .send()?;
 +    let TokenStep::Complete { token } = response.output.token_step()? else {
 +        return Err("Login requires another step".into());
 +    };
 +    let api = Client::builder("https://api.vpsfree.cz")
 +        .token(token.expose_secret())
 +        .build()?;
 +    // Or replace the login and client setup above with an existing token:
 +    // let api = Client::builder("https://api.vpsfree.cz").token("TOKEN").build()?;
 +
 +    let response = api.vps().index().limit(10).send()?;
 +    for vps in response.output {
 +        if let (Some(id), Some(hostname)) = (vps.id, vps.hostname) {
 +            println!("{} {}", id, hostname);
 +        }
 +    }
 +    Ok(())
 +}
 +</code>
 +
 +See the [[https://github.com/vpsfreecz/vpsadmin-rust-client#readme|client README]]
 +for other actions, asynchronous calls and Rust requirements.
  
  
manuals/vps/api.txt · Last modified: by aither

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki