ownCloud 9.0 for developers

The public developer API of ownCloud aims to be stable over different releases, which allows developers to have their applications work across ownCloud releases. To enable developers writing more diverse applications and to make their life easier, for this release ownCloud has gained 408 public API methods. 20 functions were deprecated, which means they will be removed in future versions of ownCloud (in 3 years, as a rule). Read on to find out what’s new and how to use it!

Much of the work around the 9.0 release was aimed at making ownCloud even more scalable for the needs of big organizations that are using ownCloud, such as CERN. This is also reflected in the public API changes which were mostly aimed at providing functionality to enable this.

However, for regular application developers we’ve also made adjustments and added new functionality. In the following we cover some of the changes introduced by the 9.0 release.

Polyfills for Older PHP Versions

While not necessarily a change to the public API, we believe that it is time to allow developers to use some of the functionality of newer PHP versions, as well as in older releases.

This has been done by adding the Symfony Polyfills for PHP 5.5, PHP 5.6 and PHP 7.0. The polyfills basically check whether a function exists in this PHP version, and if not, a generic fallback is used.

Effectively this makes the following PHP functions accessible to developers of ownCloud:

• boolval
• json_last_error_msg
• array_column
• hash_pbkdf2
• password_* functions (from ircmaxell/password_compat)
• hash_equals (part of hash extension)
• ldap_escape (part of ldap extension)
• intdiv
• preg_replace_callback_array
• error_clear_last
• random_bytes and random_int (from paragonie/random_compat)
• *Error throwable classes

Being able to use newer PHP functions like this has removed the need for us to provide generic fallbacks and, thus, makes our code easier to maintain. For example \OCP\Security\StringUtils::equals can now simply be replaced by hash_equals.

New APIs

When it comes to new APIs, most are focused on providing the new features in ownCloud 9.0 to application developers, such as tagging or commenting. This way people with the need for customized solutions can adjust these, just like with the file cache. Scalability, by integrating deeper into underlying storage systems, is one reason why you’d want to do that, and some other important public API changes are also included below for this specific purpose.

Commenting

ownCloud 9.0 introduces the ability to comment on files. Huge installations may want to store this information in another way, which is possible using these public APIs:

• \OCP\Comments\ICommentsManager
• Abstracts the access and creation of comments.
• \OCP\Comments\IComment
• Allows custom implementations of storages for comments

The principle of caching – animated

File Cache

The file cache is a huge part of ownCloud, and by using the new public APIs, it is possible to integrate it in a file system like, for example, CERN is doing:

• \OCP\Files\Cache\ICache / \OCP\Files\Cache\ICacheEntry
• Allows custom integrations of metadata for storages.
• \OCP\Files\Cache\IPropagator
• Allows a custom implementation for the ETag and MTime propagation.
• \OCP\Files\Cache\IScanner
• Allows custom file scanners for a storage
• \OCP\Files\Cache\IUpdater
• Allows custom implementations for cache updates
• \OCP\Files\Cache\IWatcher
• Allows custom implementations for watching a storage for changes

Shares

We have completely rewritten the sharing code to make it easier to maintain, more reliable and to avoid surprises for users – the user-visible changes are minimal, but important. Developers, you will benefit from the fact that the sharing information can now be completely stored on any storage system.

• \OCP\Share\IManager / \OCP\Share\IProviderFactory / \OCP\Share\IShare
• Allows custom implementations for storing share information

Locking

Locking information can now also be stored in anywhere.

• \OCP\Files\Storage\ILockingStorage
• Allows custom implementations for storing locks

Tagging

Tagging information can also be stored however you like:

• \OCP\SystemTag\ISystemTag / \OCP\SystemTag\ISystemTagManager / \OCP\SystemTag\ISystemTagManagerFactory
• Allows custom implementations for storing tags

Notifications

ownCloud 9.0 allows application developers to integrate our notification API. This API also allows you to define custom actions like accepting or denying an event.

• \OCP\Notification\IAction / \OCP\Notification\IManager / \OCP\Notification\INotification / \OCP\Notification\INotifier
• Allows integration with the notification app

More Security Through an Even Stricter CSP

Security is a key requirement for ownCloud. To prevent Cross-Site Scripting vulnerabilities, we’re employing a strict Content-Security-Policy. This means that we’re basically instructing the browser to only communicate with trusted endpoints and not to execute inline Javascript.

While this is a great thing, and applications could already modify their policies, this is only applied to their own views. So if, for example, a Chat application was hooking into any other view, it could not modify the policy.

In ownCloud 9.0 we have hardened the CSP again and have given people the possibility to inject a default policy using \OCP\Security\IContentSecurityPolicyManager::addDefaultPolicy.

Some More Niceness

In addition, some missing methods have been added to the API. It is now, for example, possible to escape like parameters or use ILIKE in the query builder.

• \OCP\IDBConnection::escapeLikeParameter
• Escapes a parameter in a way to be used safely in a LIKE query. Prevents “LIKE” injections.
• \OCP\DB\QueryBuilder\IExpressionBuilder::iLike
• Adds the case insensitive LIKE parameter to the public API of the query builder.
• \OCP\Files\FileInfo::getChecksum
• Allows getting the checksum for a file

Deprecated APIs

Note that ownCloud has a policy of supporting deprecated APIs for three years after we notify users of deprecation. This gives developers enough time to properly port their applications in order to use the new API, and should keep applications working for a long time.

Deprecations can, in this release, be mostly found within functions that we consider to have a negative impact on performance, as well as in areas which didn’t turn out to be useful for external developers or overly simplified APIs.

For example, \OCP\BackgroundJob\IJobList::getAll has been deprecated as well as some methods in \OCP\Files\Cache\ICache, which turned out not to scale properly due to missing pagination.

Furthermore, \OCP\Route\IRouter has been deprecated since this API turned out not to be used by external developers, and was very implementation specific. This limited us in core to enhance the performance of ownCloud even further since we’re bound to this implementation.

\OCP\Security\ISecureRandom is also now easier to use than before. Instead of specifying the strength manually, one can now call \OCP\Security\ISecureRandom::generate directly and strong secure random strings are generated.

Combined, these changes show a further maturing of the ownCloud public API, strengthening our ecosystem. We hope you will enjoy writing apps with the new API and your feedback is more than welcome, either here, in github or on our developer mailing list!

Thanks to Lukas Reschke for providing content for this blog.