ownCloud Planet

Welcome to ownCloud News, our contributor blog roll. ownCloud contributors should ask to get added!

Opinions are the responsibility of those who express them. See our privacy policy.

If you'd like to stay up to date with ownCloud news you could also subscribe to our newsletter!

Evert Pot
Working with HAL in PUT requests
December 15, 2016

At my new company, we’re developing a REST api. We’re trying to strike the balance between ‘easy to use’ and sticking to the rules of REST, and that’s given us more than a few unforseen benefits. When you work within a framework that a lot of people have spent time thinking about, there’s a lot of answers if you know where to look.

Originally this service was built using the JSON API specification, but we’ve thankfully adjusted our course early in the process and rewrote everything to use HAL instead.

Whereas JSON API is almost like an “ORM over HTTP”, HAL does a lot less for you though, so it’s not really an apples-to-apples type of comparison.

HAL really is just a document format for a hypermedia API, like HTML is for hypertext. It doesn’t tell you how to express your domain model, and doesn’t really tell you how to use HAL to submit changes.

Expressing relationships

The way a relationship should be expressed in HAL is using a link. For example, every user might be part of a team, so when I GET a user, I might receive something like this:

{
  "firstName" : "Evert",
  "lastName" : "Pot",

  "_links" : {
    "self" : { "href" : "/team/5/user/4234" },
    "team" : { "href" : "/team/5" }
  }
}

Here we see the link self, which is the uri for this user, and the team it belongs to. This works pretty well. We made a really strong effort to absolutely never expose database id’s anywhere in our documents, as the URI is ultimately the real identifier, and we don’t want clients to start composing these urls on their own. We also don’t want to create two types of unique identifiers (database id’s and URIs) and force users to have to think about which to use in which situation.

Adding a new user

In this example, adding a new user to a team is fairly simple. Since this user relation to the team is a sort of ‘belongsTo’ relationship, a new user could be added using a request such as this:

POST /team/5/user HTTP/1.1
Content-Type: application/vnd.foo-bar.hal+json

{
  "firstName" : "Roxy",
  "lastName" : "Kesh"
}

Since the target ‘collection’ is /team/5/user we can infer from that that the team for this will be /team/5.

It turns out that most of our relationships actually follow that model. Lots of them are basically a ‘1 to many’ relationship. It’s not always possible to follow this model though.

Expressing relations in a PUT request

I have another fictional example that’s somewhat similar to our real-life problem. Say we have a list of blog posts. They all need to be in one category.

For reasons I won’t go into, it did not make sense to have a structure such as:

/category/personal/post/5

So we have 2 distinct URL structures. Our categories might look a bit like this:

/category/personal
/category/animals
/category/vomit

And the response to a GET request to a blog post might look like this:

{
   "title": "Why I ran away",
   "date" : "2016-12-14T20:43:23Z",
   "contents" : "...",

   "_links": {
      "self" : { "href" : "/post/5" },
      "category" : { "href" : "/category/animals" }
   }
}

Pretty simple. There’s a blog post, and it expresses via a category relation type in what category it’s in. But now we want to change the category with PUT.

There’s not that much information out there from people who do this.

On the HAL Primer page for PhlyRestfully, the following is straight-up mentioned:

If POST-ing, PUT-ting, PATCH-ing, or DELETE-ing a resource, you will usually use a Content-Type header of either application/json, or some vendor-specific mediatype you define for your API; this mediatype would be used to describe the particular structure of your resources without any HAL “_links”. Any “_embedded” resources will typically be described as properties of the resource, and point to the mediatype relevant to the embedded resource.

This is one of the top hits for this Google search and pretty much implies that a HAL document (with _links) is only meant to be returned from a GET request and not sent along with a PUT. Two different media-types depending on which direction the data flows.

They can get away with it though, because they express relationship as both id’s and links, which I definitely believe is the wrong way to go about it. So when PhlyRestfully updates a resource, they follow a bit of an odd convention. If I followed it, my PUT request should look like this:

{
   "title": "Why I ran away",
   "date" : "2016-12-14T20:43:23Z",
   "contents" : "...",

   "category" : { "id" : "animals" }
}

When I asked him about this, part of his answer was:

@evertp I see HAL more as a response format, not a request format. But there's nothing saying you can't use it in either direction.

— weierophinney (@mwop) September 26, 2016

Anyway, this was a bit unsatisfying. Not only because it meant introducing the id everywhere, but I also really want clients to be able to just do a GET request, make minimal modifications to the document and use the exact same format for PUT.

When reading the HAL mailing list, it certainly does seem that many just provide links in the PUT request. Here’s a good example:

https://groups.google.com/forum/?fromgroups=#!searchin/hal-discuss/put/hal-discuss/0-CYh0oFUUo/wx8fBLqKSVUJ

Here poster asks whether he should use _embedded in PUT requests. Having the _links there seem like a given.

However, looking again at a whole bunch of the public HAL apis that exists, most of them completely ignore the notion of using _links as a real relationship and either use id-properties as well, or just provide _links separately, completely redundant.

Here’s a bunch:

Apparently both Amazon and Comcast also use HAL, but I had trouble finding their API documentation.

Our decision

We’re gonna stick to our guns and let clients create new relationships using a _links property in a PUT request.

If you are creating a new blog post, and want it to be filed under a certain category, this how how it looks like:

POST /blog/ HTTP/1.1
Content-Type: application/vnd.blog.hal+json

{
   "title": "Why I came back",
   "date" : "2016-01-15T08:44:23Z",
   "contents" : "...",

   "_links": {
      "category" : { "href" : "/category/animals" }
   }
}

_links is optional

Because _links are almost always server-controlled with a few exceptions, and might be a bit confusing for new users, we decided that we’re going to make specifying the _links in PUT requests optional. For the most part they are ‘meta data’ and not part of the core resource representation, and want to keep it somewhat simple.

This goes somewhat against the rules if you follow HTTP strictly. After all, a PUT request should completely replace the target resource. This is definitely something I choose to not strictly follow though. It rarely makes real sense.

But making _links optional creates a new problem. What if the category in our blog post is optional, and we want to to remove the category from an existing post.

Well, since _links normally is optional, this would not do the trick:

PUT /blog/6 HTTP/1.1
Content-Type: application/vnd.blog.hal+json

{
   "title": "Why I came back",
   "date" : "2016-01-15T08:44:23Z",
   "contents" : "...",
}

Instead, we’re opting for using the about:blank to specifically mark the link as removed:

PUT /blog/6 HTTP/1.1
Content-Type: application/vnd.blog.hal+json

{
   "title": "Why I came back",
   "date" : "2016-01-15T08:44:23Z",
   "contents" : "...",

   "_links" : {
      "category" : { "href" : "about:blank" }
   }
}

Is this crazy? It seemed like the sane solution to us. If you have an opinion, I would love to hear it!

read more



Klaas Freitag
Raspberry based Private Cloud?
December 11, 2016

Here is something that might be a little outdated already, but I hope it still adds some interesting thoughts. The rainy Sunday afternoon today finally gives the opportunity to write this little blog.

Recently an ownCloud fork was coming up with a little shiny box with one harddisk, that can be complemented with a Rapsberry Pi and their software, promoting that as your private cloud.

While I like the idea of building a private cloud for everybody (I started to work on ownCloud because of that idea back in the days), I do not think that this example of gear is a good solution for private cloud.

In fact I believe that throwing this kind of implementations on the table is especially unfortunate because if we come up with too many not optimal proposals, we waste the  willingness of users to try it. This idea should not target geeks who might be willing to try ideas on and on. The idea of the private cloud needs to target at every computer user who wants to store data safely, but does not want to care about longer than ever necessary. And with them I fear we only have very little chances, if one at all, to introduce them to a private cloud solution before they go back to something that simply works.

Here are some points why I think solutions like the proposed one are not good enough:

Hardware

That is nothing new: The hardware of the Raspberry Pi was not designed for this kind of usecases. It is simply too weak to drive ownCloud, which is an PHP app plus database server that has some requirements on the servers power. Even with PHP7, which is faster, and the latest revisions of the mini computer, it might look ok in the beginning, but after all the neccessary bells and whistles were added to the installation and data run in, it will turn out that the CPU power is simply not enough. Similar weaknesses are also true for the networking capabilities for example.

A user that finds that out after a couple of weeks after she worked with the system will remain angry and probably go (back) to solutions that we do not fancy.

One Disk Setup

The solution comes as one disk setup: How secure can data be that is on one single hardisk? A seriously engineered solution should at least recommend a way to store the data more securely and/or backup, like on an at homes NAS for example.
That can be done, but requires manual work and might require more network capabilities and CPU power.

Advanced Networking

Last, but for me the most important point: Having such a box in the private network requires to drill a whole in the firewall, to allow port forwarding. I know, that is nothing unusual for experienced people, and in theory little problem.

But for people who are not so interested, that means they need to click in the interface of their router on a button that they do not understand what it does, and maybe even insert data by following an documentation that they have to believe. (That is not very much different from downloading a script from somewhere letting it do the changes which I would not recommend as well).
Doing mistakes here could potentially have a huge impact for the network behind the router, without that the person who did it even has an understanding for.

Also DynDNS is needed: That is also not a big problem in theory and for geeks, but in practice it is nothing easily done.

With a good solution for private cloud, it should not be necessary to ask for that kind of setups.

Where to go from here?

There should be better ways to solve this problems with ownCloud, and I am sure ownCloud is the right tool to solve that problem. I will share some thought experiments that we were doing some time back to foster discussion on how we can use the Raspberry Pi with ownCloud (because it is a very attractive piece of hardware) and solve the problems.

This will be subject of an upcoming blog here, please stay tuned.

 


read more



Thomas Müller
Contacts 1.5.1 has been released!
December 5, 2016

In the past days some heavy bug fixing did take place in the ownCloud Contacts app.

DAVDroid sync bug because of illegal REV value

While the DAVDroid community was debugging an issue it has been detected that we are actually setting an invalid REV value with the VCard as soon as a user is editing a contacts in the Contacts App. I’d like to thank https://github.com/rfc2822 for debugging and verifying the fix the patch.

Import Enhancements

While importing VCards we are now verify that only VCards of version 3.0 and 4.0 are imported and in addition any server error is now reported back to the user.

bildschirmfoto-von-2016-12-01-15-17-24

Copy CardDAV Url to Clipboard

Especially on mobile devices it was quite hard to select and copy the full CardDAV Url from the settings panel. This is now much easier with the copy to clipboard button which is powered by the angular library ngclipboard.

copyclipboard

Date formatting issues

Before 1.5.1 some dates have been stored in the VCard with an invalid format. My thanks got to Joas Schilling for fixing this issue.

Remove ugly auto correction from input fields

This patch was provided by John Molakvoæ – Thanks a lot!

Have fun using ownCloud Contacts 1.5.1!

Please keep in mind that this is open source and you can contribute and make this app even more awesome!

Reach out to the developers via GitHub or start a discussion on ownCloud Central!


read more



ownCloud.com
ownCloud and GÉANT offers Education Customers Special Pricing for Collabora
December 1, 2016

ownCloud, GÉANT, and Collabora have teamed up to offer our users Collabora Online with in the ownCloud service suite. Collabora Online provides educational and research institutions with a scalable, commercially supported version with long term support, signed security updates and a Service Level Agreement maintained by ownCloud GmbH.

Our education and research users will now be able to access their office documents within the ownCloud web front, author new content, share their work and collaboratively work on the same document with others, all while others can see changes in real time and take over editing. No longer are users plagued with version conflicts that could occur while working independently on documents.

Check out some of the great features users will benefit from:

  • Collaborative editing
  • Author new content
  • View and edit documents, spreadsheets and presentations
  • Preservation of layout and formatting of documents
  • Insert comments, reply to comments
  • File revision history
  • Full screen presentation
  • Support for any modern web browser
  • Increase productivity while you stay in full control of sensitive corporate data
  • Auto Saving

Now, students assigned to work in projects can collaborate together, separately, saving precious time that we all know many students have little of. No longer will they need to meet up, dedicating a set amount of time to work on a project, now they can improve productivity through multitasking.

Because ownCloud values the importance of education, starting from January 2017 qualified educational users will be able to add the Collabora functionality to their ownCloud platform for a reduced price. As a special introductory offer, now there is an even further 20% discount available for all new purchases and renewals of matching ownCloud licenses ordered before 31 January 2017. To find out more about ownCloud pricing and the Collabora Online option, please contact Peter Szegedi at GÉANT. Read GÉANT Announcement here.

To experience the power and functionality of Collabora online click here to request a free demo.

The post ownCloud and GÉANT offers Education Customers Special Pricing for Collabora appeared first on ownCloud.

read more



ownCloud
Email Data Size Limitations eliminated with Outlook Plug-In
November 23, 2016

Today we announced the release of a new Microsoft Outlook plug-in. This means that you can easily send secure files as well as whole folders. Now, instead of attachments, the plug-in will automatically add the links to corresponding files within ownCloud, without having to change your workflow. The plug-in is fully integrated into Outlook, easy to use, and works with secure SSL encryption.

BW-Tech GmbH developed the Outlook plug-in as an extension to its ownCloud-based file sharing solution Epikshare. But after customization, the plug-in is now available for all ownCloud users.

Outlook is still the default solution for emails, calendars, and tasks at many companies. With the new plug-in, we are opening up a new dimension in secure email-based file sharing for the more than ten million ownCloud users. Many Microsoft Exchange operators have explicitly asked us for an Outlook plug-in. Thanks to our partnership with BW-Tech, we are now able to make one available for the market!

The Outlook plug-in ensures that the link to the files and the password needed for downloading them are automatically sent separately for added security. And to ward off viruses, all the data is checked for malicious software before being sent to the ownCloud server. For those users who often send large amounts of data, this will benefit them greatly, as the data is accessed via a link, meaning there are no size limitations when it comes to sending your data.

The plug-in is now available for both our subscription and community users in German and in English. Be sure to test it out with a 30 day free trial today. After the free trial period the PlugIn will be priced at 5.95 €/p.a.

 

Screenshot gallery

 

Setup video

read more