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

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 protected]"
}

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 protected]"}",
  "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