ownCloud Planet

Being at FOSDEM 2017 in Brussels we had a very special eye catcher with us: a 3D-printer, producing our own clouds. The also store your data very secure (because of the strong neodym magnets), … well at least in form of paper notes at your fridge or whiteboard.

Jürgen – both ownCloud employee and running FabLab Nuremberg – took the printer with him. As many of you asked, here are some information regarding our setting:

The 3D printer is called »TinyBoy Fabricator«  – An open design 3D printer for student and kids. It’s a small, easy to build, yet very affordable machine. The size is just 15 x 15 x 21cm , even smaller than an A4 sheet of paper, therefore, it fits on regular computer desks. The design aims as an entry-level machine for students and newbies to learn 3D modeling technology and train for creative thinking. It is an opensource hardware design, licensed under CC BY-SA 4.0 and fully exposed on https://github.com/HKCOTA/TinyBoy with

• a complete bill of materials for standard stock items like motors and electronics.
• complete 2D-drawings ready for use with a lasercutter to produce all other parts from 3mm plastic sheets (typically in bright neon colored arylic) at your nearby Hackerspace or FabLab.

http://www.thingiverse.com/thing:701548 features all the needed files in ready to use formats and has a good technical overview.

At FabLab Nuremberg Jürgen developed some practical add-ons and modifications, as well as a collection of improvements that would go into the next redesign iteration. There are multiple extra for fans keeping the machine cool, a stand for the filament spool, extra legs, LED illumination and an added OrangePi to make it print without a permanent USB connection to a laptop or workstation.

His collection of existing and future ideas are at https://github.com/fablabnbg/tinyboy.

The software referenced there includes machine profiles for cura and slic3r. The already realized add-ons as mentioned above live at

• http://www.thingiverse.com/thing:1533722
• http://www.thingiverse.com/thing:1533739
• http://www.thingiverse.com/thing:1453794

Feel free to use the info as an entry point to build up your own printer and as well to printout your personal ownCloud fridge magnets. Or print out our ownCloud cookie cutter. It’s all opensource.

About ownCloud, PaperHive and Collabora

Researchers, students, medicine and engineering specialists are among the core ownCloud users and ownCloud’s team is committed to support them in the management and creation of research data and texts. A recent partnership with Collabora was ownCloud’s response to users’ need to write collaboratively online. It resulted in the release of the Collabora Online Development Edition, a VM containing LibreOffice Online and ownCloud Server.

To help users read, reference and discuss already published academic texts, ownCloud now starts a cooperation with PaperHive, a web platform for collaborative reading.

Researchers read 12-25 hours a week depending on their discipline. Yet, understanding research articles and books – some of the most complex documents in the world – is hard and inefficient in isolation. Students and inexperienced researchers waste time trying to decipher these texts alone, senior researchers dig through folders of articles irrelevant for their own work, and all at some point might repeat unknowingly others’ mistakes or include these as a citation in their own paper.

PaperHive looks at how the web platform could transform reading into a more social and active process of collaboration. It is a cross-publisher layer of interaction on top of published research documents that enables contextual and structured discussions in real time. PaperHive’s main benefits for users:

• annotate and discuss published academic articles, books and textbooks
• ask and answer questions, help and benefit from the knowledge, opinions and results of your colleagues and the broad research community
• keep up-to-date with the newest developments around a specific research topic
• improve research texts by discovering and correcting mistakes publicly, make complex concepts more accessible
• share your thoughts and discoveries with the research community and increase your visibility as a researcher
• give structured feedback to your colleagues
• if you are a teacher, you can make lectures and seminars much more engaging for students

Close to 14 million academic articles and books can currently be read and discussed with PaperHive.

Transforming Reading Into Process of Collaboration

One of the greatest ownCloud features is sharing. Folders or files can be shared with groups, individual users or using a password protected or public links.

The PaperHive documents in this shared folder allow copyright-compliant sharing of research publications with groups of users. By using the `Discuss` button in the file list a user is quickly redirected to the PaperHive page. The `Discuss` button also shows the current number of discussions online.

Transform your lectures, research and engineering work into process of collaboration with ownCloud, PaperHive and Collabora!

Add PaperHive document to ownCloud

The PaperHive plugin is shipped with the new file menu button “PaperHive Document”, which allows adding the documents found on the PaperHive website at https://paperhive.org. These are no different to your regular .doc or .jpg files and will behave the same as any other files in the ownCloud user interface.

Clicking on the “PaperHive Document” button will ask you for a PaperHive URL or DocID, displaying helpful information in the yellow popup on top of your file list. You are free to choose submitting just DocID or whole URL!

The user can now easily keep up-to-date with new developments around publications of interest and start public or private discussions to better understand or improve academic texts.

DocID is an unique book identifier, which can be found in the URL of the document at https://paperhive.org, as shown in the example below, where URL is https://paperhive.org/documents/0tsHJq1-yyVZ and unique DocID is 0tsHJq1-yyVZ.

Found Book ID has to be inserted into the field below and confirmed pressing ENTER.

Your PaperHive Book is now in your synchronisation folder!

Test and contribute

ownCloud invites everybody to download and test the PaperHive Integration and give us back your comments.

ownCloud will be present @ 2017 FOSDEM in Brussels from Feb. 4th to 5th. You’ll find our table at K (level 1, group C). Meet our managing director Holger Dyroff, senior developer and packaging manager Jürgen Weigert as well as our senior support engineer Carlos Damken among others and ask them anything about ownCloud.

FOSDEM is a free event for software developers to meet, share ideas and collaborate. Every year, thousands of developers of free and open source software from all over the world gather at the event in Brussels. FOSDEM 2017 will take place at ULB Campus Solbosch on Saturday 4 and Sunday 5 February 2017. The full schedule and list of stands are now online.

ownCloud is an open source project. That means it is yours. You can study, improve and share it however you like. Do you want to get a certain improvement in ownCloud? Did you find a problem? Do you want to help translate, promote or document ownCloud? Become part of the ownCloud Community and help us liberate data across the globe!

Each contribution – either code, bug report, Q&A, … – will be valued with some exclusive swag. So make sure to see us in Brussels!

Keep an eye on our newest iOS App for ownCloud, which will enter the AppStore still today

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:

• viagogo API
• artsy API
• SlimPay API.

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!