Shared App Spaces with Live JSON Data

Part 1: Platform Concept + Backend Service

I love programming! And I love to experiment and create new web applications. This is why my website is called POCZone.net (with POC = Proof of Concept).

I’m currently rewriting the entire website and want to take you with me on the journey.

This story shares the concept behind the platform. It introduces the Backend Service, which is already up and running. The online instance of the backend with a generated UI and the open source code is linked below!


Requirements? A lot in common…

Most of my applications are note taking apps — ToDo lists, Kanban boards, diaries, wikis, etc. I discovered, they have a lot in common:

  1. User context: They require authentication and data must be stored confidentially.
  2. Spaces: I want multiple isolated spaces for each app (e.g. Work, Private, Project A, Project B, …).
  3. Collaboration: I want to share spaces with other users and grant reader / writer / admin permissions.
  4. JSON data storage: A storage solution that stores JSON Objects for ID strings in each space suffices in most cases.
  5. Incremental live updates: I want to sync incremental data updates in both directions (client ↔ server). In case of concurrent use, these updates shall be synced instantly (client 1 → server → client 2).

The POCZone.net Platform Concept

The concept of the POCZone.net platform is to handle all the common parts, so I can focus on the apps themselves.

My Backend Service provides all the functionality. Its operations are outlined below. It is written in Java with Servlet API + JDBC MySQL + JSON API. All operations are executed with a HTTP POST request to the endpoint of the operation. The input is URL encoded form data. The output is JSON. So it is very easy to consume the service as a client. I use application error codes. The backend has an automatically generated user interface, which is great for testing. This can be provided, because I use my own technical framework, where operations are declared with their name, input, output and errors.

[… now we enter the future …]

The Portal Application is the main user interface for the Backend Service. It’s what the user will see at https://poczone.net/. It handles authentication. It provides space overview, management and sharing for the various apps I provide. And it launches the apps.

Apps are started with an integration call in an iframe. The call has a “dataToken” URL parameter. The app can then include my JavaScript Client API and access JSON data with live updates for the space behind the data token.

Third party apps are possible!



POCZone.net Backend Service Operations

These are the operations provided by the Backend Service:

Authentication (auth/*)

Operations: auth/login | auth/register | auth/logout.

After successful calls to login or register, a session token is returned. This token grants access for most of the other operations.

Space Management and Sharing (spaces/*)

Operations: spaces/create | spaces/getMine | spaces/edit | spaces/share | spaces/leave.

You can create, retrieve, rename and leave spaces. Spaces have names and are linked to an app. You can share them with other users with four permission levels:

  1. NONE is used to revoke all permissions.
  2. READER has read-only access to the space data.
  3. WRITER has read/write access to the space data.
  4. ADMIN has read/write access to the space data and can manage the space and share it.

At the time of writing, there is no way to retrieve user names from the service. It is assumed that the user knows the names of collaborators. Spaces are also kept secret, unless you created them or were invited via the share operation.

Granting Data Access (data/token/*)

Operations: data/token/create | data/token/revoke

Let’s access some data! The data token operations provide temporary read/write access to JSON data in a space.

With the creation of the data token, the space is selected. The token can have read/write or read-only permissions. The access with a data token is temporary and can be revoked.

Why do data tokens even exist? The concept assures apps can read (and write) data on behalf of the user in opened spaces, but not escape this context. They won’t know the session token. They can’t access other spaces, because they won’t know other data tokens.

Data tokens have the format {spaceUUID}/{R or RW permission level}/{random secret}.

JSON Data Storage (data/json/*)

Operations: data/json/post | data/json/getDiff | data/json/getByIDs

Now that we have the data token, we can finally read and write JSON data. This is what an App would do, while the platform handles all the rest. The JSON Data Storage operations allow remote origins.

Each space saves JSON Objects by their ID.

Assume the space data is:

{“H”: {“fn”:”Hendrik”}, “S”: {“fn”:”Stephan”}, “M”: {}}

Let’s say, we want to create “C”, update “M”, delete “H” (and keep “S”). An app can commit the following diff with the post operation:

{“C”: {“fn”:”Carsten”}, “M”: {“fn”:”Martin”}, “H”: null}

The new space data is then:

{“S”: {“fn”:”Stephan”}, “M”: {“fn”:”Martin”}, “C”: {“fn”:”Carsten”}, ”H”:null}

A running app may already know the first state. In order to bring it up to date, it gets the exact diff that was committed. This is done with the getDiff operation. Its request has the last known time stamp “since”. It optionally waits for new data with long polling. Future versions may use web sockets.

Objects can also be retrieved explicitly by their IDs.


Summary

I love to build experimental note taking web applications! I designed a platform that handles all the common parts. These are authentication, space management and sharing, and JSON data storage with incremental live updates. The Backend Service is up and running and published as open source software.


What’s next?

Next, I will…

  1. Finish the Portal Application (v1.0).
  2. Finish the JavaScript Client API to be included by apps (v1.0).
  3. Simplify my existing Apps with the use of the new Client API.
  4. Create new Apps.
  5. Include third party apps, when someone wants to create one. You? :-)

I publish the code at GitHub and write about the progress on medium. If you’re interested, stay tuned!