ownCloud Server 8.1 delivers the result of a strong focus on code quality and testing. A big part of that has been improvements to the API. ownCloud 8.1 introduces over 190 new public API functions and deprecates over 50 old functions. We will discuss the ownCloud API and the changes this release brings for developers.
The ownCloud API
The ownCloud API (Application Program Interface) is what allows third party developers to build ownCloud Server apps you can install in your ownCloud. It also makes it possible for developers to interface with an running ownCloud server from other applications like sync clients or calendar applications running on your phone or desktop computer. Developers can and do use ‘private’ API’s as well, interfaces used within ownCloud and not meant for external applications. This has the downside that it makes apps dependent on a specific ownCloud release, as a newer version often changes these internal interfaces. A public interface can change as well, but when a function has to be removed, this is announced (“this and this method is deprecated, please use this other method”) and the ‘old’ function will remain in place for a time to give developers time to migrate and avoid breaking older apps. ownCloud Server 8.1 deprecates over 50 functions, replacing them with improved versions.
However, sometimes developers are forced to use these internal API’s as no public API has been made available yet. This is why ownCloud Server 8.1 introduces over 190 new public API functions.
PHPDoc Annotations
All public API methods now have a PHPDoc annotation which denotes when the function became available, if and when it was deprecated and if so, what should be used in its place. This is using the in 8.1 newly introduced @since tags in combination with already existing older @deprecated PHP docs tag. Here is an example:
/**
* Returns the request uri, even if the website uses one or more reverse proxies
* @return string the request uri
* @deprecated 8.1.0 Use \OCP\IRequest::getRequestUri
* @since 5.0.0
*/
public static function getRequestUri() {
return \OC::$server->getRequest()->getRequestUri();
}
In this case the function getRequestUri would have been introduced with ownCloud version 5.0.0 to developers and with 8.1.0 we deprecated it in favor of IRequest::getRequestUri which allows dependency injection and thus makes unit-testing easier. See documentation here.
Using these annotations developers can see directly when an API was introduced as well as when they get removed. This bring us closer to our goal of building a platform for application developers with ownCloud. Going forward, our goal is to keep API’s working for three years after we have announced their deprecation. Due to security concerns and technical problems this is not always possible but we are committed to making it work as much as technically possible.
As part of our efforts to improve code quality, this release deprecates over 50 API’s, offering better replacements. Let’s go over some of them.
Performance
OCP\App::addNavigationEntry allowed developers to add navigation to the ownCloud app navigation (the thing you see all apps listed). The actual implementation however had the drawback that every app that registered their entry resulted in more operations happening such as generating the final URLs even when they were not required (such as when accessing via WebDAV). For a small performance gain on all requests developers shall use the navigation manager \OCP\INavigationManager (\OC::$server->getNavigationManager()->add()).
Cleanups
Several APIs already had proper public replacements before but were not officially deprecated. This has been done now in 8.1. They were deprecated mainly because they were static and thus Dependency Injection was not possible which makes unit-testing harder. Some API’s were deprecated and replaced because the API was sub-optimal from a ownCloud architecture or API design point of view.
The replacements are usually straight forward. You can find the list in the documentation here.
New and Improved
As mentioned, this release introduces over 190 new public API functions. Let’s go over the most interesting new additions.
Encryption
ownCloud Server 8.1 features encryption 2.0, allowing developers to write their own encryption modules. This gives them complete control over how the data should be encrypted. The public interfaces and PHPDoc can be found in OCP\Encryption.
As a result, other older functions such as OCP\Util::encryptedFiles have been deprecated as they are not used anymore.
More Powerfull Request Class
To support developers in creating unit-testable code as well as to put code that belongs together at the same place the OCP\IRequest interface now supports a lot more functionality such as: get the remote address (which will work great with proxies together now with 8.1 as well!) of the user, get the used protocol (i.e. http or https), get the used request URI, the path info, script name or perform a check whether the used user agent matches an applied regex, as well as some other useful methods.
The older methods in OCP\Util, have been deprecated:
– OCP\Util::getServerHost has been deprecated in favor of \OCP\IRequest::getServerHost
– OCP\Util::getServerProtocol has been deprecated in favor of \OCP\IRequest::getServerProtocol
– OCP\Util::getRequestUri has been deprecated in favor of \OCP\IRequest::getRequestUri
– OCP\Util::getScriptName has been deprecated in favor of \OCP\IRequest::getScriptName
New mailer
Sending mails with older ownCloud releases was cumbersome, one was effectively forced to use the static OCP\Util::sendMail which has grown over time and was quite hard to use properly.
With ownCloud 8.1 we introduced a new mailer based on Swift. Using this new mailer it is possible to handle mails and messages in an object-oriented way. It also introduces many new capabilities such as setting a reply-to addresses or setting BCC and CC recipients.
The result is that OCP\Util::sendMail has been deprecated in favor of the \OCP\Mail interfaces.
Preview providers
ownCloud supports previews for some file types such as images or text files and until now all this code was part of the ownCloud core. That was a barrier for new developers who wanted to add new preview providers since being in core puts a relatively strict maintenance burden on developers. Moreover, some file types simply don’t have to be supported by every ownCloud installation out there. In short, it would be nice to allow installing and removing support for individual mimetype previews in ownCloud, and this is now possible.
Developers can register an preview provider using OCP\IPreview::registerProvider and implement OCP\Preview\IProvider in their applications to offer new preview abilities.
New API for cropping and other image manipulations
Basic image manipulations is now possible
The \OCP\IImage class has been introduced which allows basic image manipulations such as getting information about an image (size / width / orientation) and also to resize, crop and do some further basic image manipulations.
This is especially awesome combined with the new “preview providers” feature, as it allows you to make sure the thumbnail looks good.
New ClientService for HTTP requests
Interaction with other web services or the ability to request content from them is often a requirement. With the new ClientService you can send request to others services in a breeze. This includes the ability to also send POST, GET or directly stream the request to a file to save memory. For complete PHPDoc documentation checkout the OCP\Http\Client interfaces.
As a result, \OCP\IHelper has been completely deprecated as it only contained a single function getUrlContent which can be achieved by \OCP\Http\Client\IClientService already.
Content Security Policy
See this blog about security improvements in ownCloud 8.1 for details.
App store
A last area of improvement for developers will be visible when publishing apps. ownCloud 8.1 introduces the ability for users to install Experimental apps, that is, all apps from the online app store on apps.owncloud.com, seamlessly from the built in App Store app. The video below shows how this works.
To get your app from ‘experimental’ to ‘approved’ state, the app will have to be reviewed by the ownCloud community. You can read about the process here. We’re still working out some kinks in the new process and you can expect a blog post with more details next week.
All together, this release introduces many important improvements to architecture and API’s of ownCloud, making it easier to build quality apps and keep them working on newer ownCloud releases for a long time. ownCloud Server 8.1 is shaping up to be a very interesting release for developers!
