Introduction to Pydio APIs

Setup - I/O Formats

Checking API's are working

In this documentation, we will assume that you already have a working Pydio server, and especially that you went through the steps to make sure that the REST API are correctly configured. Basically, this just requires making sure that your web server is correctly configured for RewriteRules. If you are not sure, please check the administrator guide : https://pydio.com/en/docs/v8/checking-apis

Input / Output Expected Formats

Being over the place for a long time now, Pydio (formerly called AjaXplorer), exposes a set of API's that may have been written long ago, as well as more recent ones. For this reason, and although we are working hard to make that more homogeneous, some API's may output XML, some may output JSON, etc.. That said, our most common format still is a SOAP-like format :

  • Input : URI parameters (see below) + POST parameters if required
  • Output : XML (content type is text/xml).

Input and output are expected to use UTF-8 encoding.

Api V1

Building REST Api URL's

All the Pydio actions that can be addressed via the standard Pydio clients (web, mobile, sync) can be accessed directly through various standard protocols by your own client application.

Base URI

On a default Pydio installation, the rest API is configured to be available on https://yourpydio.com/api/. This can be modified by changing the .htaccess definitions for the rewrite rules.

Workspace ID or ALIAS

Once logged in to Pydio, a "user" is always logged to a given "workspace". Even when you are looking the welcome page, you are in fact logged on a special "workspace", powered in background by the access.ajxp_home plugin. Depending on this workspace you are browsing, one or many plugins may be active, and as actions are always contributed by plugins, actions are accessible or not via the API depending on this current "workspace" state as well.

For this reason, every call to the REST api will be built as follow:

/api/workspace_id_or_alias/action_name/{paramValue1}/{paramValue2}/...

This is important to keep in mind. In our generated API documentation, we will generally use {default} as the workspace alias, but you will have to replace it with your own. For specific actions like users/groups provisioning, you must be working on the Admin Panel workspace, and the API docs thus use /api/settings/ instead of /api/default/.

Action Name

Finally, the next mandatory part of the URI is the name of the action to be performed. It is defined in each plugins under the <actions> xml elements.

Api V2

Starting with Pydio 7, we have rewritten the REST API from ground up to stick more closely to the REST standards. The api V2 is accessible under yourpydio/api/v2 and provides access points for managing files and folders, as well as a whole set of commands for provisioning users and workspaces.

Authentication

Our REST API supports basic http authentication, with two types of credentials :

  • Either the standard login / password of a Pydio user
  • Or a pair of Key/Secret as generated by our keystore plugin. The pairs are generated on-demand by a logged-in user, and can be revoked from within Pydio UI.

Alternative Accesses

Using PHP on Command-line

Alternatively to the RESTfull access, all actions can also be triggered directly on the server where Pydio is installed, via the Command Line. For that, we provide a cmd.php script a the root of the Pydio installation folder, that can be called using PHP.

Similarly to building the REST URL to call, you would build the command with the following system:

php cmd.php -u=USERNAME -p=PASSWORD -r=WORKSPACE_ID -a=ACTION --param1=value1 --param2=value2

Where the four first parameters are mandatory, and the following ones will depend on the ACTION called. Beware that -u, -p, -r, -a take a single dash whereas any additional parameter takes a double-dash (--).

Using our legacy "SOAP" access point

REST is cool and has emerged as a reference protocol for consuming API's. But for example our Web client does not use this REST access, but a "Soap-like" session-based access point instead. You can use this as well, but this requires a more complex negocation for authentication against the server. The advantage can be that we store some data in the session and this makes requests faster to load.

To call an action defined by the API directly through this endpoint, you would call the following

https://yourpydio.com/index.php?get_action=ACTION_NAME&secure_token=SECURE_TOKEN&param1=value1&param2=value2

This request expects a valid PHP Session ID passed through the Cookie Headers. SECURE_TOKEN is NOT the PHP session ID, it is an additional token added for CSRF protection. Basically, opening a valid session is an 3-steps process :

  • Call get_boot_conf action to get a SECURE_TOKEN
  • Post a login action with user credentials (login & password)
  • Call switch_repository action to log the user on a given workspace ( = repository ).

If login is successful, you can then call any action that may be active on the current workspace.

Back to top