POCZone #2: Backend Service
HTTP Interface for Authentication + Space Management + JSON Data Storage
I finished the Backend Service for the rewrite of my website POCZone.net! POC is of Proof of Concept. For an always up-to-date index article with the bigger picture of the rewrite, visit this story:
Explore
The Online Instance of the Backend Service is up and running. You can visit it here:
The source code is available at GitHub:
Design
The Backend Service provides all the functionality! It is written in Java with Servlet API + JDBC MySQL + JSON API.
The code is split into a “framework” and a “backend” part. The framework part defines interfaces for applications with their operations and input / output / error signatures.
It also serves such applications. 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. The framework also provides an automatically generated user interface, which is great for exploring and testing!
The backend part implements the special POCZone.net application with all its operations with a minimum of overhead!
Now lets get into the operations provided…
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:
- NONE is used to revoke all permissions.
- READER has read-only access to the space data.
- WRITER has read/write access to the space data.
- 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.
Read more about the Portal Application in the next story!
