Skip to content

Interacting with the collaboration server

Jump to bottom
Jonathan Van der Cruysse edited this page May 17, 2018 · 11 revisions

The collaboration server is designed to interconnect clients. Specifically, it serves the following use cases:

  1. authenticating users,
  2. negotiating locks on files, and
  3. sending and receiving files from clients.

To communicate with the server, clients can use a REST API. This guide discusses the functionality offered by the API and how to use it.

Authenticating users

Requesting a token

Every time a user wants to sign in to the server, they should initially request a token from the server. Such a token uniquely identifies the user's session. Note that tokens are ephemeral. If a user signs out and then signs in again, they will receive a different token.

A new token can be requested by performing the following request:

POST http://193.190.127.184:8042/auth/request-token

The response is a unique token as plain text.

Signing in

A newly requested token is initially not associated with a user of our service. To make that association, send the user to the following URL via a browser window (possibly using a pop-up to avoid messing up the client-side application's internal state). Replace {token} with a token from the server.

GET http://193.190.127.184:8042/auth/auth/{token}

The server will then redirect the user to a GitHub authorization website. Upon consenting to granting UnSHACLed access to their GitHub account, the user will again be redirected to the collaboration server, which will associate the token with the user's GitHub account.

Checking if a token is authenticated

To tell if a token is associated with a GitHub account, send the following request. Replace {token} with a token requested from the server.

GET http://193.190.127.184:8042/auth/is-authenticated/{token}

The response will be true if the token is associated with a GitHub account; otherwise, false.

Accessing information about users

It is sometimes useful to get basic information about authenticated users. The collaboration server sports a number of APIs for this purpose.

Querying a user's name

Send a request to the URL below. The user's name is returned as a string.

GET http://193.190.127.184:8042/user/name/{token}

Querying a user's GitHub login name

Send a request to the URL below. The user's GitHub login is returned as a string.

GET http://193.190.127.184:8042/user/login/{token}

Querying a user's email

Send a request to the URL below. The user's GitHub email is returned as a string.

GET http://193.190.127.184:8042/user/email/{token}

Getting the user's repositories

To grab a list of a user's repositories, send a request to the URL below.

GET http://193.190.127.184:8042/user/repo-list/{token}

File access

Listing all files

To get a list of all files in a repository, send a request to the URL below.

GET http://193.190.127.184:8042/repo/file-names/{repo-owner}/{repo-name}/{token}

The response body to that request consists of a list of strings, each representing a path to a file.

Reading a file

To request a file as text from a repository, send a request to the URL below.

GET http://193.190.127.184:8042/repo/file/{repo-owner}/{repo-name}/{token}/{file-name}

Requesting a lock on a file

Users can only edit a file if they have a lock on that file. Users can check if they have a lock, acquire the lock and release the locks using the following APIs, respectively.

GET http://193.190.127.184:8042/repo/has-lock/{owner}/{repoName}/{token}/{filePath}
POST http://193.190.127.184:8042/repo/request-lock/{owner}/{repoName}/{token}/{filePath}
POST http://193.190.127.184:8042/repo/relinquish-lock/{owner}/{repoName}/{token}/{filePath}

The has-lock and request-lock APIs return a Boolean value: true means that the lock is assigned to the user, false means the opposite.

Creating or updating a file

A user that holds a lock on a file can update or create that file (a lock can be acquired on a file that doesn't exist yet; in fact, a lock must be acquired before creating a file). The API to do so is fairly straightforward.

PUT http://193.190.127.184:8042/repo/file/{repo-owner}/{repo-name}/{token}/{file-name}

Attach the (updated) file contents as the request's body. A well-formed request will return HTTP 200 (OK) if an existing file was updated or HTTP 201 (Created) if a new file was created.

Polling a file for changes

Authenticated users may want to stay up to date with the latest version of a file. A specialized API exists for just this purpose.

GET http://193.190.127.184:8042/repo/poll-file/{owner}/{repoName}/{token}/{filePath}

To allow for efficient polling, a timestamp can optionally be included as the request body. If the timestamp is omitted, the server acts as if the epoch was provided as a timestamp.

If the file referenced by the request has been updated since the timestamp in the request, the server's response will state that. It will also include the contents of the latest version of the file.

{
  "isModified": true,
  "lastChange": "2018-05-13T09:14:12.1477890-06:00",
  "contents": "Edit for file polling testing purposes"
}

Otherwise, the server's response will omit the contents field.

{
  "isModified": false,
  "lastChange": "2018-05-13T09:14:12.1477890-06:00"
}

From the client's perspective, the polling workflow is designed to work like so:

  1. Created a timestamp string variable and set it to the empty string.
  2. Poll the file and include the timestamp variable as the request body. If the file has changed, update the client's state. Regardless of whether the file has changed, set the timestamp variable to the lastChanged field of the server's reply to the poll.
  3. Wait for a while.
  4. Go to step two.

Creating a repository

You can ask the client to create a repository by sending a request to the URL below. The resulting repository's owner will be the account of the user associated with the token. Does nothing if the repository already exists.

POST http://193.190.127.184:8042/repo/create-repo/{repo-name}/{token}

The resulting response body consists of the repository slug of the newly created or pre-existing repository, that is, it is {repo-owner}/{repo-name}.

Workspaces

To allow users to roam from one device to the other and still leave their editor in a consistent state, the server supports storing and retrieving workspaces.

To set the contents of an authenticated user's workspace, send the following request with the workspace contents as the request body.

PUT http://193.190.127.184:8042/workspace/{token}

To fetch the contents of an authenticated user's workspace, send the following request. The workspace is returned as a string.

GET http://193.190.127.184:8042/workspace/{token}
Clone this wiki locally