Overview of Cloudron REST API
4 min read api

Overview of Cloudron REST API

One of the immediately visible aspects of the Cloudron is it's web based modern user interface. This user interface makes it easy for anyone to run apps on their server. Behind the scenes, there is a comprehensive REST API that powers this (Angular!) UI.

In this post, we will see how developers and integrators can use the REST API to automate various tasks in the Cloudron. I like to think of this feature as giving a REST API to an Ubuntu server.

Scope of REST API

The Cloudron UI is a client-side application that makes REST API calls for all of it's tasks. As such, you can automate any of the tasks that you can perform in the UI including:

  • Adding users, groups and mailboxes
  • Installing, configure, clone, backup and restore apps
  • Get a log of significant events
  • Change settings like the avatar, timezone, auto update pattern, certificates etc.
  • Backup and update the entire Cloudron

Using the REST API involves the following steps:

  • Create an API access token.
  • Use the access token in the Authorization header or as access_token query parameter to authenticate requests.
  • Follow the API docs to find the request endpoint and parameters.

Creating a API token

You can get an API token from the API Access menu of your Cloudron.

Overview

For illustration, we will create a user Dewey, add them to a nephews group. We will then install a Wordpress blog at location blog and give all the nephews access to that blog.

I will use my cloudron at the cloudron.info domain for the examples below.

Creating user 'dewey'

We start out by adding user dewey with his email. As we have set invite to true, Dewey will get an email invitation to join the Cloudron and set his password.

If you have the email server enabled, a mailbox named dewey@cloudron.info is automatically created.

$ curl -kX POST -H "Content-Type: application/json" -d '{ "email":  "dewey@duckfamily.com", "username": "dewey", "invite": true }' https://my.cloudron.info/api/v1/users?access_token=93d1f3e57feb10d7af9ae00828d3cf3240bd538ed674a75bd45627e7e857abbc
{
  "id": "uid-b51d8bd4-0f10-45e2-b927-565367bd9f33",
  "username": "dewey",
  "displayName": "",
  "email": "dewey@duckfamily.com",
  "alternateEmail": null,
  "groupIds": [],
  "resetToken": "f13e1364790e94d3a965739064898a03942812551defa5f3c0bdb9bf760b29db"
}

Creating group 'nephews'

Creating a group is equally straightforward. Simply send a POST request with the name of the group.

If you have the email server enabled, a group mailing list named nephews@cloudron.info is automatically created.

$ curl -kX POST -H "Content-Type: application/json" -d '{ "name": "nephews" }' https://my.cloudron.info/api/v1/groups?access_token=93d1f3e57feb10d7af9ae00828d3cf3240bd538ed674a75bd45627e7e857abbc
{
  "id": "gid-fdd88ec8-5ccb-48da-b700-de2620c6b564",
  "name": "nephews"
}

Adding user 'dewey' to group 'nephews'

We use the set members API to add Deweyto the nephews group.

$ curl -kX PUT -H "Content-Type: application/json" -d '{ "userIds": [ "uid-b51d8bd4-0f10-45e2-b927-565367bd9f33" ] }' https://my.cloudron.info/api/v1/groups/gid-fdd88ec8-5ccb-48da-b700-de2620c6b564/members?access_token=93d1f3e57feb10d7af9ae00828d3cf3240bd538ed674a75bd45627e7e857abbc

The result of the above API calls can be seen in the UI immediately:

Installing 'Wordpress'

Using the app install API, we can set a location for the app and also assign the groups that have access to the app.

$ curl -kX POST -H "Content-Type: application/json" -d '{ "location": "blog", "appStoreId": "org.wordpress.cloudronapp", "accessRestriction": { "groups": [ "gid-fdd88ec8-5ccb-48da-b700-de2620c6b564" ] } }' https://my.cloudron.info/api/v1/apps/install?access_token=93d1f3e57feb10d7af9ae00828d3cf3240bd538ed674a75bd45627e7e857abbc
{
  "id": "1d752aad-c358-41a9-9043-602bee5324e8"
}

The status of the app can be checked using the get app API.

$ curl -kX GET -H "Content-Type: application/json" https://my.cloudron.info/api/v1/apps/1d752aad-c358-41a9-9043-602bee5324e8?access_token=93d1f3e57feb10d7af9ae00828d3cf3240bd538ed674a75bd45627e7e857abbc{
  "id": "1d752aad-c358-41a9-9043-602bee5324e8",
  "appStoreId": "org.wordpress.cloudronapp",
  "installationState": "installed",
  "installationProgress": "",
  "runState": "running",
  "health": "healthy",
  "location": "blog",
  "accessRestriction": {
    "groups": [
      "gid-fdd88ec8-5ccb-48da-b700-de2620c6b564"
    ],
    "users": []
  },
  "lastBackupId": null,
  "manifest": {
    "id": "org.wordpress.cloudronapp",
    "title": "WordPress",
    "author": "WordPress developers",
    "description": "This app packages WordPress 4.7.2.\n\nWordPress is web software you can use to create a beautiful website or blog.\nWe like to say that WordPress is both free and priceless at the same time.\n\nThe core software is built by hundreds of community volunteers, and when\nyou’re ready for more there are thousands of plugins and themes available\nto transform your site into almost anything you can imagine. Over 60 million\npeople have chosen WordPress to power the place on the web they call “home” \n— we’d love you to join the family.\n\n### Apps\n\n* [Android](https://play.google.com/store/apps/details?id=org.wordpress.android&hl=en)\n* [iOS](https://itunes.apple.com/us/app/wordpress/id335703880?mt=8&uo=6&at=&ct=)\n\n",
    "tagline": "Transform your site into almost anything you can imagine",
    "version": "0.7.2",
    "healthCheckPath": "/",
    "httpPort": 8000,
    "manifestVersion": 1,
    "website": "https://wordpress.org/",
    "contactEmail": "apps@cloudron.io",
    "configurePath": "wp-admin/",
    "icon": "logo.png",
    "addons": {
      "mysql": {},
      "localstorage": {},
      "sendmail": {},
      "ldap": {}
    },
    "tags": [
      "blog",
      "cms",
      "weblog",
      "ghost"
    ],
    "mediaLinks": [
      "https://wordpress.com/home.logged-out/page-rey/img/apps-devices-2x.jpg",
      "https://wordpress.com/home.logged-out/page-rey/img/product/media-cortado-images-2x.jpg",
      "https://wordpress.com/home.logged-out/page-rey/img/product/ui-cortado-fonts-2x.jpg",
      "https://wordpress.com/home.logged-out/page-rey/img/product/ui-cortado-colors-2x.jpg"
    ],
    "changelog": "* Use latest base image 0.10.0\n* Update screenshots\n",
    "postInstallMessage": "This app integrates optionally with Cloudron SSO.\n\nWhen using Cloudron SSO, Cloudron adminstrators are automatically made WordPress\nadministrators. Non-administrators get the `editor` role by default.\n\nWhen _not_ using Cloudron SSO, the `admin` password is `changeme`.\n\nYou can access the dashboard directly at `/wp-admin/` (trailing slash is\nimportant!).\n\n",
    "optionalSso": true,
    "dockerImage": "cloudron/img-062037096d69bbf3ffb5b9316ad89cb9:71d18bb0-bd72-4661-a237-02f9d341f67b"
  },
  "portBindings": {},
  "iconUrl": "/api/v1/apps/1d752aad-c358-41a9-9043-602bee5324e8/icon",
  "fqdn": "blog.cloudron.info",
  "memoryLimit": 0,
  "altDomain": null,
  "xFrameOptions": "SAMEORIGIN",
  "sso": true,
  "debugMode": null
}

We can verify that the blog was installed and is running in the UI:

Summary

Cloudron has a complete REST API that can be used to automate repetitive tasks and build integrations.

You might also like...

Jun
22

REST API

1 min read

Popular tags

release apps installation pricing cli