Skip to content

Group Server API

Jump to bottom
David Fialho edited this page Jan 18, 2018 · 5 revisions

Incomplete! Still in progress...

This page describes the API provided by the Group Server

To Do

  • define what each type is
  • add requests/responses to create a new group
  • include diagrams

Types

  • String
  • ID
  • Signature
  • JSON
  • Int

Requests/Responses

Request

Must be a POST request. The parameters of the request are the following.

Parameter Type Description
author ID Author's public key/ID
signature Signature Payload signed with the author's private key
payload Any Value(s) of the request. If there are multiple values this is a JSON object

Example with a single value in the payload,

author: AKJ832948SDHKKlS
signature: MNAOSDKNLSAKDNLLASDLNALDS
payload: value

Example with multiple values in the payload,

author: AKJ832948SDHKKlS
signature: 32948SD7AJDKBAHKKAKJ8lSDD
payload: {
  "param1": "value1",
  "param2": "value2"
}

Response

The response is a JSON object. The returned object contains at least two parameters: a status code and a message, as shown below.

Parameter Type Description
status Int An HTTP status code (200 means success)
message String Short message explaining what went wrong

Each individual response adds other parameters when necessary.

Example of successful response without parameters (an ACK),

{
  "status": 200,
  "message": "OK"
}

Example of successful response with parameters,

{
  "status": 200,
  "message": "OK",
  "param1": "value1",
  "param2": "value2"
}

Example of an error response,

{
  "status": 401,
  "message": "authentication failed"
}

Inviting a new user

invitation-diagram

Invite Operation

A registered user invites a new user (not registered) to join its group.

Request

The payload of an invite request contains multiple values. The table bellow describes each value.

Value Type Description
inviteeId ID ID of user inviting a new user
invitedId ID ID of new user
invitedEmail String Email of new user

The inviteeId must match the ID of the request's author.

Example,

author: AKJ832948SDHKKlS
signature: 32948SD7AJDKBAHKKAKJ8lSDD
payload: {
  "inviteeId": "AKJ832948SDHKKlS",
  "invitedId": "BKJ47992JALSDJAA",
  "invitedEmail": "email@example.com"
}

Response

The server does not need to send any explicit parameter. Therefore, it only sends an ACK, as shown bellow.

{
  "status": 200,
  "message": "OK"
}
Code Error Name Cause
401 Unauthorized Authentication failed
403 Forbidden The user making the request is not registered
403 Forbidden Invited user is already registered

Join Operation

A user that received an invitation code by email tries to join the group using that code.

Request

The payload of an join request has a single value: a secret, of type String, which corresponds to the secret in the email sent by group server.

Example,

author: AKJ832948SDHKKlS
signature: 90ASDJSDJ9023RJDFOA90JF0F
payload: ASJD199DLASKD0128SD7AJDKB

Response

The response to a join request contains multiple values. The table bellow describes each value.

Value Type Description
invitation String JSON object as a string representing the initial invitation
inviteeSignature Signature Invitation signed by the user who invited the new user
serverSignature Signature Invitation signed by the group server

The invitation is composed by the following parameters.

  • inviteeId: ID
  • invitedId: ID
  • invitedEmail: String

Example,

{
  "status": 200,
  "message": "OK",
  "invitation": "{"inviteeId": "AKJ832948SDHKKlS","invitedId": "BKJ47992JALSDJAA","invitedEmail": "email@example.com"}",
  "inviteeSignature": "32948SD7AJDKBAHKKAKJ8lSDD",
  "serverSignature": "ASASASKKJFH19021ION1LEP1P"
}

Notice the commas used on the invitation's value. They are used because the value is actually a string, not a JSON object. That string is necessary for the client/user to validate the signatures.

Code Error Name Cause
400 Request Request format is invalid
400 Request Request is missing some parameter
401 Unauthorized Authentication failed
403 Forbidden The user is already registered
403 Forbidden Secret is not valid

Confirm Join Operation

A user confirms that it wants to join a group after the Group Server has accepted that user.

Request

The payload of a confirm-join request has a single value: the serverSignature, of type Signature, which corresponds to invitation signed by the group server.

Example,

author: AKJ832948SDHKKlS
signature: HPFALSFANSCLSACLLN79ASDJL
payload: ASASASKKJFH19021ION1LEP1P

The server should also inspect the request's signature.

Response

The response to a confirm-join request contains multiple values. The table bellow describes each value.

Value Type Description
registration String JSON object as a string with the user's ID and the group ID
signature Signature Registration signed by the global server

The registration is composed by the following parameters.

  • userId: ID, ID of the user trying to register
  • groupId: ID, ID of the group the user is joining

Example,

{
  "status": 200,
  "message": "OK",
  "registration": "{"userId": "BKJ47992JALSDJAA", "groupId": "NJS195HAS19JASFH"}",
  "signature": "8AS0SAFJF0AF09ASFJ0JJ77UA"
}

Notice the commas used in the registration's value. They are used because the value is actually a string, not a JSON object. That string is necessary for the client/user to validate the signature.

Code Error Name Cause
400 Request Request format is invalid
400 Request Request is missing some parameter
400 Request Server signature specified was not verified
401 Unauthorized Authentication failed
403 Forbidden The user is already registered
403 Forbidden There is no invitation for this user
500 Internal Server Error Communication with global server failed

Clone this wiki locally