Creating Atomic Data using Atomic-Server
Here is everything you need to get started:
- Atomic-Server and its features
- Running Atomic-Server locally (optional)
- Creating an Agent
- Creating your first Atomic Data
- There's more!
Atomic-Server and its features
Atomic-Server
is the reference implementation of the Atomic Data Core + Extended specification.
It was developed parallel to this specification, and it served as a testing ground for various ideas (some of which didn't work, and some of which ended up in the spec).
Atomic-Server is a graph database server for storing and sharing typed linked data. It's free, open source (MIT license), and has a ton of features:
- âïļ Dynamic schema validation / type checking using Atomic Schema. Combines safety of structured data with the
- ð Fast (1ms responses on my laptop)
- ðŠķ Lightweight (15MB binary, no runtime dependencies)
- ðŧ Runs everywhere (linux, windows, mac, arm)
- ð Embedded server with support for HTTP / HTTPS / HTTP2.0 and Built-in LetsEncrypt handshake.
- ðïļ Browser GUI included powered by atomic-data-browser. Features dynamic forms, tables, authentication, theming and more.
- ðū Event-sourced versioning / history powered by Atomic Commits
- ð Synchronization using websockets: communicates state changes with a client. Send a
wss
request to/ws
to open a webscocket. - ð§° Many serialization options: to JSON, JSON-AD, and various Linked Data / RDF formats (RDF/XML, N-Triples / Turtle / JSON-LD).
- ð Full-text search with fuzzy search and various operators, often <3ms responses.
- ð Pagination, sorting and filtering using Atomic Collections
- ð Authorization (read / write permissions) and Hierarchical structures powered by Atomic Hierarchy
- ðē Invite and sharing system with Atomic Invites
- ð File management: Upload, download and preview attachments.
- ðĨïļ Desktop app: Easy desktop installation, with status bar icon, powered by tauri.
Running Atomic-Server locally (optional)
In this guide, we'll can simply use atomicdata.dev
in our browser without installing anything.
So you can skip this step and go to Creating your first Atomic Data.
But if you want to, you can run Atomic-Server on your machine in a couple of ways:
- Using a desktop installer: download a desktop release from the
releases
page and install it using your desktop GUI. - Using a binary: download a binary release from the
releases
page and open it using a terminal. - Using Docker is probably the quickest:
docker run -p 80:80 -v atomic-storage:/atomic-storage joepmeneer/atomic-server
. - Using Cargo:
cargo install atomic-server
and then runatomic-server
to start.
Atomic-Server's README contains more (and up-to-date) information about how to use it!
Open your server in your browser.
By default, that's http://localhost:9883
.
Fun fact: ⚛
is HTML entity code for the Atom icon: â.
The first screen should show you your Drive. You can think of this as your root folder. It is the resource hosted at the root URL, effectively being the home page of your server.
There's an instruction on the screen about the /setup
page.
Click this, and you'll get a screen showing an Invite.
Normally, you could Accept as new user
, but since you're running on localhost
, you won't be able to use the newly created Agent on non-local Atomic-Servers.
Therefore, it may be best to create an Agent on some other running server, such as the demo Invite on AtomicData.dev.
And after that, copy the Secret from the User settings
panel from AtomicData.dev, go back to your localhost
version, and press sign in
.
Paste the Secret, and voila! You're signed in.
Now, again go to /setup
. This time, you can Accept as {user}
.
After clicking, your Agent has gotten write
rights for the Drive!
You can verify this by hovering over the description field, clicking the edit icon, and making a few changes.
You can also press the menu button (three dots, top left) and press Data view
to see your agent after the write
field.
Note that you can now edit every field.
You can also fetch your data now as various formats.
Try checking out the other features in the menu bar, and check out the collections
.
Again, check out the README for more information and guides!
Now, let's create some data.
Creating an Agent
Before you can create new things on AtomicData.dev, you'll need an Agent. This is your virtual User, which can create, sign and own things.
Simply open the demo invite and press accept. And you're done!
Creating your first Atomic Data
Now let's create a Class.
A Class represents an abstract concept, such as a BlogPost
(which we'll do here).
We can do this in a couple of ways:
- Press the
+ icon
button on the left menu (only visible when logged in), and selecting Class - Opening Class and pressing
new class
- Going to the Classes Collection and pressing the plus icon
The result is the same: we end up with a form in which we can fill in some details.
Let's add a shortname (singular), and then a description.
After that, we'll add the required
properties.
This form you're looking at is constructed by using the required
and recommended
Properties defined in Class
.
We can use these same fields to generate our BlogPost resource!
Which fields would be required in a BlogPost
?
A name
, and a description
, probably.
So click on the + icon
under requires
and search for these Properties to add them.
Now, we can skip the recommended
properties, and get right to saving our newly created BlogPost
class.
So, press save, and now look at what you created.
Notice a couple of things:
- Your Class has its own URL.
- It has a
parent
, shown in the top of the screen. This has impact on the visibility and rights of your Resource. We'll get to that later in the documentation.
Now, go to the navigation bar, which is by default at the bottom of the window. Use its context menu to open the Data View
.
This view gives you some more insight into your newly created data, and various ways in which you can serialize it.
There's more!
This was just a very brief introduction to Atomic Server, and its features. There's quite a bit that we didn't dive in to, such as versioning, file uploads, the collaborative document editor and more... But by clicking around you're likely to discover these features for yourself.
In the next page, we'll dive into how you can create an publish JSON-AD files.