Skip to content

10. API

Jump to bottom
Ludovic edited this page Nov 1, 2024 · 33 revisions

Repomanager exposes an API that allows performing certain actions.

From a client host:

  • Register or unregister a host into Repomanager
  • Send general host informations to Repomanager
  • Send packages informations to Repomanager
  • Retrieve the configuration of a host profile from Repomanager

From a desktop:

  • Import source repositories
  • Upload a package to a repository
  • Rebuild repository metadata

API key

An API key can be retrieved from userspace.

Once generated, copy the key and keep it safe. This key is used to authenticate with the API and to perform certain actions when there is no host Id+token pair available.

If a new API key is generated, then all old keys become invalid and unusable.

https://github.com/user-attachments/assets/7ece907e-c900-427d-9630-351c3d242de5

Endpoints

API URL: https://<FQDN>/api/v2

Endpoint and method Authentication method Parameter(s) Description Example
/host/registering
POST
 <APIKEY>
hostname (required)
ip (required)
 Register host to Repomanager and retrieve host Id and token 
curl -L --post301 -s -q -X POST -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{"hostname":"<FQDN>","ip":"<IP>"}' https://repomanager.mydomain.net/api/v2/host/registering
/host/registering
DELETE
 <HOST_ID> and <HOST_TOKEN>   Unregister host from Repomanager 
curl -L --post301 -s -q -X DELETE -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" https://repomanager.mydomain.net/api/v2/host/registering
/host/status
PUT
 <HOST_ID> and <HOST_TOKEN>
hostname (optional)
os (optional)
os_version (optional)
os_family (optional)
type (=virtualization type) (optional)
kernel (optional)
arch (optional)
profile (optional)
env (optional)
agent_status (optional)
linupdate_version (optional)
reboot_required (optional)
 Send host general informations to Repomanager 
curl -L --post301 -s -q -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '{"hostname":"myfqdn.localhost","os":"ubuntu","os_version":"22.04","os_family":"Debian","type":"Bare metal","kernel":"5.15.0-89-generic","arch":"x86_64","profile":"PC","env":"prod","agent_status":"running","linupdate_version":"2.2.2","reboot_required":"false"}' https://repomanager.mydomain.net/api/v2/host/status
/host/packages/installed
PUT
 <HOST_ID> and <HOST_TOKEN>
installed_packages (required)
Each package must be separated by a comma and contains the package name and the version number separated by a pipe
 Send list of installed packages to Repomanager 
curl -L --post301 -s -q -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '{"installed_packages":"accountsservice|22.07.5-2ubuntu1.4,acl|2.3.1-1,acpi-support|0.144,acpid|1:2.0.33-1ubuntu1,add-apt-key|1.0-0.5,adduser, etc..."}' https://repomanager.mydomain.net/api/v2/host/packages/installed
/host/packages/available
PUT
 <HOST_ID> and <HOST_TOKEN>
available_packages (required)
Each package must be separated by a comma and contains the package name and the version number separated by a pipe
 Send list of available packages updates to Repomanager 
curl -L --post301 -s -q -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '{"available_packages":"apparmor|3.0.4-2ubuntu2.3,libapparmor1|3.0.4-2ubuntu2.3,libapparmor1:i386|3.0.4-2ubuntu2.3,libgd3|2.3.3-9+ubuntu22.04.1+deb.sury.org+1,libgd3:i386|2.3.3-6+ubuntu22.04.1+deb.sury.org+1,lintian|2.114.0ubuntu1.3"}' https://repomanager.mydomain.net/api/v2/host/packages/available
/host/packages/event
PUT
 <HOST_ID> and <HOST_TOKEN> events (required) Send packages events history (installed / upgraded / removed / downgraded) to Repomanager 
curl -L --post301 -s -q -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '
  {
      "events": [
          {
              "date_start": "2022-11-01",
              "date_end": "2022-11-01",
              "time_start": "12:47:30",
              "time_end": "12:47:57",
              "command": "/usr/bin/apt upgrade",
              "upgraded": [
                  {
                      "name": "firefox-locale-en",
                      "version": "106.0.3+linuxmint1+vanessa"
                  },
                  {
                      "name": "php8.1-opcache",
                      "version": "8.1.12-1+ubuntu22.04.1+deb.sury.org+1"
                  },
              ],
          },
          {
              "date_start": "2022-11-05",
              "date_end": "2022-11-05",
              "time_start": "12:21:40",
              "time_end": "12:21:41",
              "command": "/usr/bin/apt install php8.1-curl",
              "installed": [
                  {
                      "name": "php8.1-curl",
                      "version": "8.1.12-1+ubuntu22.04.1+deb.sury.org+1"
                  }
              ]
          },
          {
              "date_start": "2022-11-16",
              "date_end": "2022-11-16",
              "time_start": "16:26:15",
              "time_end": "16:26:20",
              "command": "/usr/bin/apt autoremove",
              "removed": [
                  {
                      "name": "linux-headers-5.15.0-50-generic",
                      "version": "5.15.0-50.56"
                  },
                  {
                      "name": "linux-modules-5.15.0-50-generic",
                      "version": "5.15.0-50.56"
                  }
              ]
          }
      ]
  }' https://repomanager.mydomain.net/api/v2/host/packages/event
/profile
GET
<APIKEY>
or
<HOST_ID> and <HOST_TOKEN>
  Retrieve all available profiles configuration 
curl -L -s -q -X GET -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" https://repomanager.mydomain.net/api/v2/profile | jq
/profile/<PROFILE>
GET
<APIKEY>
or
<HOST_ID> and <HOST_TOKEN>
  Retrieve profile's global configuration 
curl -L --post301 -s -q -X GET -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" https://repomanager.mydomain.net/api/v2/profile/app_server | jq
/profile/<PROFILE>/excludes
GET
<APIKEY>
or
<HOST_ID> and <HOST_TOKEN>
  Retrieve profile's package exclusion configuration 
curl -L --post301 -s -q -X GET -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" https://repomanager.mydomain.net/api/v2/profile/app_server/excludes | jq
/profile/<PROFILE>/repos
GET
<APIKEY>
or
<HOST_ID> and <HOST_TOKEN>
  Retrieve profile's repositories configuration 
curl -L --post301 -s -q -X GET -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" https://repomanager.mydomain.net/api/v2/profile/app_server/repos | jq
/snapshot/<SNAPSHOT_ID>/upload
POST
 <APIKEY>
files (required)
Upload a package to a repository snapshot. <SNAPSHOT_ID> can be retrieved when you browse a snapshot from the REPOS list:
https://github.com/lbr38/repomanager/assets/54670129/d849e588-d4c9-459a-9e5c-98f3d5b37b19 
curl -L --post301 -s -q -X POST -H "Authorization: Bearer <APIKEY>" -F "files=@/tmp/mypackage.deb" https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/upload
/snapshot/<SNAPSHOT_ID>/rebuild
PUT
 <APIKEY>
gpgSign (required)
Rebuild repository snapshot metadata. <SNAPSHOT_ID> can be retrieved when you browse a snapshot from the REPOS list:
https://github.com/lbr38/repomanager/assets/54670129/d849e588-d4c9-459a-9e5c-98f3d5b37b19 
curl -L -s -q -X PUT -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json" -d '{"gpgSign":"true"}' https://repomanager.mydomain.net/api/v2/snapshot/<SNAPSHOT_ID>/rebuild
Clone this wiki locally