Overview

amigo-platform is the main backend application for the amigo project. It will provide features and mechanisms for the following problems:

  • Authentication (login and token management)

  • Authorisation (permissions and groups)

  • User Management (Accounts, Persons, Groups)

  • Notification and messaging services

  • Multimedia management via MinIO integration

  • Video/audio call management via Jitsi integration

HTTP verbs

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource. Will return 200.

POST

Used to create a new resource. Will return 201 for success.

PUT

Used to update an existing resource as an idempotent call. May also create the resource in rare cases, e.g. if it a singleton resource.Will return 200 with Content, 204 without Content

PATCH

Used to update an existing resource, including partial updates. Will return 200 with Content, 204 without Content

DELETE

Used to delete an existing resource. Will return 204

HTTP status codes

RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully. An update to an existing resource has been applied successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information.

401 Unauthorized

User is not logged in and Authorization is necessary

403 Forbidden

User is authenticated but Authorization is not given on this resource

404 Not Found

The requested resource did not exist, the URL describes nothing

405 Method not allowed

The requested path does not support this operation

409 Conflict

Another similar resource already exist, Creation is not possible

415 Unsupported Media Type

Only json is supported

451 Unavailable for legal reasons

A create or update request cannot be accepted due to use of reserved/restricted input

Headers

Requests

Every authenticated request needs at least the following header(s):

Content-Type: application/json
Accept: application/json
Authorization: Bearer $SECRET_ACCESS_TOKEN
Amigo-Person-Id: $UUID of own person

Attention: Currently providing the Amigo-Person-Id information is optional, as the first Person of Account will be used otherwise. As amigo-platform is designed to be a multi-group user system, an Account can have several Persons in different Groups. Therefore, the usage of Amigo-Person-Id is meant as specific authentication and encouraged.

Additionally it is useful to provide the

The Private Token can be obtained during authentication

Response

Content-Type: application/json;charset=UTF-8
Content-Length: $NUMBER

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Response fields

Path Type Description

errorCode

Number

Unique error code

errorName

String

Short error title

errorMessage

String

A detailed message

time

String

Timestamp of error

For example, a request that attempts to register a user with an existing username 400 Bad Request response:

Example response

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 158

{
  "errorCode" : 400,
  "errorName" : "ACCOUNT_CREATE_PASSWORD_INVALID",
  "errorMessage" : "Password is invalid",
  "time" : "2023-05-08T15:10:36.636315Z"
}

User & Groups

Authentication - /auth

POST /auth/register

Example request

$ curl 'http://localhost:8080/v1/auth/register' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/plain' \
    -d '{
  "email" : "ucvvcdkrrs@example.com",
  "password" : "uA7Q0LJ^C%AxF&dfBMtotpmATN*m1h",
  "name" : "absolute-new-name",
  "optionalGroupId" : null
}'

Request fields

Path Type Description

password

String

A plain text password

email

String

A valid email

name

String

The fullname of the user

optionalGroupId

String

When given: attaches to existing Group. If not: creating a new implicit Group

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 306

{
  "id" : "6ff0f95d-7e66-4d01-ae00-1263f287e6fa",
  "email" : "ucvvcdkrrs@example.com",
  "persons" : [ {
    "id" : "c12c2c66-c152-4ad6-b6c0-8d567e6dd94c",
    "name" : "absolute-new-name",
    "groupId" : "20ffa277-9531-473d-8a17-0a65303d0143",
    "memberType" : "OWNER",
    "avatarUrl" : null
  } ]
}

Response fields

Path Type Description

id

String

UUID

email

String

An unique email

persons

Array

All persons of that Account

createdByAccountId

String

ID of Creator Account

changeAccountToken

String

changeAccountTokenCreatedAt

String

persons[].id

String

Unique UUID of this Person

persons[].accountId

String

Unique UUID the parent Account

persons[].name

String

Fullname of this Person

persons[].groupId

String

References the Group

persons[].memberType

String

MemberType: can be ADMIN, MEMBER, ANALOGUE

persons[].avatarUrl

String

Optional URL of avatar image

Or use explicit Group registering:

Example request

$ curl 'http://localhost:8080/v1/auth/register' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/plain' \
    -d '{
  "email" : "uyepaeltwu@example.com",
  "password" : "KgXBpDX1I*Z2!p8XaE4M3+4Fp$-4+5",
  "name" : "absolute-new-name",
  "optionalGroupId" : "8f1cc325-f273-4baa-865f-e4ce38adc2d6"
}'

Request fields

Path Type Description

password

String

A plain text password

email

String

A valid email

name

String

The fullname of the user

optionalGroupId

String

When given: attaches to existing Group. If not: creating a new implicit Group

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 307

{
  "id" : "e2534a5f-8714-48d2-9d94-8c05f9274d8f",
  "email" : "uyepaeltwu@example.com",
  "persons" : [ {
    "id" : "ae0fb0c7-5b46-479c-accf-c3db25956213",
    "name" : "absolute-new-name",
    "groupId" : "8f1cc325-f273-4baa-865f-e4ce38adc2d6",
    "memberType" : "MEMBER",
    "avatarUrl" : null
  } ]
}

POST /auth/register-analogue

Example request

$ curl 'http://localhost:8080/v1/auth/register-analogue' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '{
  "name" : "absolute-new-name",
  "neededGroupId" : "5826cc3d-8cd3-4207-975a-81d0674a7ddc"
}'

Request fields

Path Type Description

name

String

The fullname of the user

neededGroupId

String

Attaches to existing Group.

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 450

{
  "id" : "f268d6c1-f380-4139-a78e-11e5f9ba287f",
  "email" : "user-1683558629985@amigobox",
  "createdByAccountId" : "58220882-7cb9-45d5-9272-d6b40e4959b6",
  "changeAccountToken" : null,
  "changeAccountTokenCreatedAt" : null,
  "persons" : [ {
    "id" : "c31fd681-073e-4557-96dd-634bf745a76d",
    "name" : "absolute-new-name",
    "groupId" : "5826cc3d-8cd3-4207-975a-81d0674a7ddc",
    "memberType" : "ANALOGUE",
    "avatarUrl" : null
  } ]
}

Response fields

Path Type Description

id

String

UUID

email

String

An unique email

persons

Array

All persons of that Account

createdByAccountId

String

ID of Creator Account

changeAccountToken

String

changeAccountTokenCreatedAt

String

persons[].id

String

Unique UUID of this Person

persons[].accountId

String

Unique UUID the parent Account

persons[].name

String

Fullname of this Person

persons[].groupId

String

References the Group

persons[].memberType

String

MemberType: can be ADMIN, MEMBER, ANALOGUE

persons[].avatarUrl

String

Optional URL of avatar image

POST /auth/login

Example request

$ curl 'http://localhost:8080/v1/auth/login' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/plain' \
    -d '{
  "email" : "email-470001@example.com",
  "password" : "password"
}'

Request fields

Path Type Description

password

String

A plain text password

email

String

A valid email

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1553

{
  "account" : {
    "id" : "33ee452f-211d-4dbb-8187-6a62ea3c65d3",
    "email" : "email-470001@example.com",
    "createdByAccountId" : null,
    "changeAccountToken" : null,
    "changeAccountTokenCreatedAt" : null,
    "persons" : [ {
      "id" : "6ffe703f-f55e-47bd-828c-5b411f8a0c61",
      "name" : "user name -470001",
      "groupId" : "d694b053-75ee-4159-a27c-205226876459",
      "memberType" : "ADMIN",
      "avatarUrl" : null
    } ]
  },
  "refreshToken" : {
    "token" : "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWFpbC00NzAwMDFAZXhhbXBsZS5jb20iLCJpYXQiOjE2ODM1NTg2MzUsImV4cCI6MTY4NzE1ODYzNSwiaXNzIjoiQU1JR08tUExBVEZPUk0iLCJhY2NJZCI6IjMzZWU0NTJmLTIxMWQtNGRiYi04MTg3LTZhNjJlYTNjNjVkMyJ9.2aAEv9WXHQHLRwF8_pRtbT5POHiNaUik4bg84qfAji4E3YxBYgZsomRU4l7yEi06GtqG7PguQTQ_Yx-T-S-9Lw",
    "subject" : "email-470001@example.com",
    "issuedAt" : "2023-05-08T15:10:35.000+00:00",
    "expiration" : "2023-06-19T07:10:35.000+00:00",
    "issuer" : "AMIGO-PLATFORM"
  },
  "accessToken" : {
    "token" : "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWFpbC00NzAwMDFAZXhhbXBsZS5jb20iLCJpYXQiOjE2ODM1NTg2MzUsImV4cCI6MTY4NzE1ODYzNSwiaXNzIjoiQU1JR08tUExBVEZPUk0iLCJhY2NJZCI6IjMzZWU0NTJmLTIxMWQtNGRiYi04MTg3LTZhNjJlYTNjNjVkMyIsInBlcnNvbnNJZHMiOlsiNmZmZTcwM2YtZjU1ZS00N2JkLTgyOGMtNWI0MTFmOGEwYzYxIl19.xoz_2SwNj9i3opoCVRHIs9DTQ_oPIFutgGjHCh3MtvYIZRAlZb4Wbx1W1aEKeEVeBxHnktbnwKK08_wvXdHfQQ",
    "subject" : "email-470001@example.com",
    "issuedAt" : "2023-05-08T15:10:35.000+00:00",
    "expiration" : "2023-06-19T07:10:35.000+00:00",
    "issuer" : "AMIGO-PLATFORM"
  }
}

Response fields

Path Type Description

account

Object

The technical Account of this user

refreshToken

Object

Long living refreshToken for token generation

accessToken

Object

Short living accessToken for authentication and authorisation

account.id

String

UUID

account.email

String

An unique email

account.persons

Array

All persons of that Account

account.createdByAccountId

String

ID of Creator Account

account.changeAccountToken

String

account.changeAccountTokenCreatedAt

String

account.persons[].id

String

Unique UUID of this Person

account.persons[].accountId

String

Unique UUID the parent Account

account.persons[].name

String

Fullname of this Person

account.persons[].groupId

String

References the Group

account.persons[].memberType

String

MemberType: can be ADMIN, MEMBER, ANALOGUE

account.persons[].avatarUrl

String

Optional URL of avatar image

refreshToken.token

String

Effective signed JWT token for authentication

refreshToken.subject

String

Account’s email for faster validations

refreshToken.issuedAt

String

DateTime of issuing

refreshToken.expiration

String

DateTime of expiration: token must be refreshed before

refreshToken.issuer

String

Authority which granted this JWT

accessToken.token

String

Effective signed JWT token for authentication

accessToken.subject

String

Account’s email for faster validations

accessToken.issuedAt

String

DateTime of issuing

accessToken.expiration

String

DateTime of expiration: token must be refreshed before

accessToken.issuer

String

Authority which granted this JWT

POST /auth/refresh-token

When performing this action to "refresh a token" you get a new "access token".

Example request

$ curl 'http://localhost:8080/v1/auth/refresh-token' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/plain' \
    -d '{
  "refreshToken" : "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWFpbC0yMUBleGFtcGxlLmNvbSIsImlhdCI6MTY4MzU1ODYyNiwiZXhwIjoxNjgzNTU4NjM0LCJpc3MiOiJBTUlHTy1QTEFURk9STSIsImFjY0lkIjoiMDVhMmQ5YzAtOTJkMC00NjkxLWEyOWMtZGQwNzBhZTgwZmRjIn0.SzoC_olNNQP3s6A1ZpNy8FuH5MkoLzbeg8Oa2o4NDZELLSd0qKPAPg9MXT1oC9v8C6zStE2YW6_5wPH0VOCIJw"
}'

Request fields

Path Type Description

refreshToken

String

Necessary refreshToken (obtained during login) for getting a new accessToken

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 544

{
  "token" : "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlbWFpbC0yMUBleGFtcGxlLmNvbSIsImlhdCI6MTY4MzU1ODYyNiwiZXhwIjoxNjg3MTU4NjI2LCJpc3MiOiJBTUlHTy1QTEFURk9STSIsImFjY0lkIjoiMDVhMmQ5YzAtOTJkMC00NjkxLWEyOWMtZGQwNzBhZTgwZmRjIiwicGVyc29uc0lkcyI6WyIyMjgyZjc2OS0yNWY0LTRmYmYtYTk2Mi1iMjM1ODkxNjg3NzkiXX0.dyIfxlLNAIylHReIePtS6eX5zNavkdhYuQv2n5ouYXJKa7agij54XdU6khcbHVSDCpVXLhjYuE71gHLkE7Myyw",
  "subject" : "email-21@example.com",
  "issuedAt" : "2023-05-08T15:10:26.000+00:00",
  "expiration" : "2023-06-19T07:10:26.000+00:00",
  "issuer" : "AMIGO-PLATFORM"
}

Response fields

Path Type Description

token

String

Effective signed JWT token for authentication

subject

String

Account’s email for faster validations

issuedAt

String

DateTime of issuing

expiration

String

DateTime of expiration: token must be refreshed before

issuer

String

Authority which granted this JWT

GET /auth/account

Get user short profile info, when already logged in.

Example request

$ curl 'http://localhost:8080/v1/auth/account' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 604

{
  "id" : "60e0fc33-160d-4d45-92fc-8b0e5d0434ca",
  "email" : "email-32@example.com",
  "createdByAccountId" : null,
  "changeAccountToken" : null,
  "changeAccountTokenCreatedAt" : null,
  "persons" : [ {
    "id" : "15ec4c1b-7bab-488e-9c37-65354b03dd38",
    "name" : "user name -32",
    "groupId" : "5826cc3d-8cd3-4207-975a-81d0674a7ddc",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  }, {
    "id" : "be761351-2320-4dd3-a5ea-766c62f99d50",
    "name" : "email-32@example.com",
    "groupId" : "d3ea1acf-1412-4ab6-9ae2-d98efe11b98e",
    "memberType" : "OWNER",
    "avatarUrl" : null
  } ]
}

Response fields

Path Type Description

id

String

UUID

email

String

An unique email

persons

Array

All persons of that Account

createdByAccountId

String

ID of Creator Account

changeAccountToken

String

changeAccountTokenCreatedAt

String

persons[].id

String

Unique UUID of this Person

persons[].accountId

String

Unique UUID the parent Account

persons[].name

String

Fullname of this Person

persons[].groupId

String

References the Group

persons[].memberType

String

MemberType: can be ADMIN, MEMBER, ANALOGUE

persons[].avatarUrl

String

Optional URL of avatar image

POST /auth/fcm-token

Set the new Firebase Cloud Messaging (FCM) token for the current user. No Data as response.

Example request

$ curl 'http://localhost:8080/v1/auth/fcm-token' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '{
  "fcmToken" : "fcm"
}'

Request fields

Path Type Description

fcmToken

String

Secret token for FCM client messages

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Groups - /groups

Groups contain all necessary Person profiles inside them. A User can just access the Groups where they have a Person profile and is at least MEMBER (default).

A Group can contain at max 1 ANALOGUE Person.

Group Model

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1187

[ {
  "id" : "7232698f-1136-4513-b3e0-49f1c161e525",
  "name" : "Group-43",
  "members" : [ {
    "id" : "52c3ffd0-7a1c-4e3e-acaa-eccb0436047d",
    "name" : "email-92@example.com",
    "groupId" : "7232698f-1136-4513-b3e0-49f1c161e525",
    "memberType" : "OWNER",
    "avatarUrl" : null
  }, {
    "id" : "84c17039-fc7c-444d-a997-49f53b290637",
    "name" : "user name -930002",
    "groupId" : "7232698f-1136-4513-b3e0-49f1c161e525",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  }, {
    "id" : "f6724366-e709-4aa8-8da8-3cd597066c98",
    "name" : "user name -94",
    "groupId" : "7232698f-1136-4513-b3e0-49f1c161e525",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  } ]
}, {
  "id" : "8b79bae9-d0f4-40de-bba6-057e521e700f",
  "name" : "Group-44",
  "members" : [ {
    "id" : "9083045d-8547-4d6e-8f24-42d0b908bc9b",
    "name" : "email-94@example.com",
    "groupId" : "8b79bae9-d0f4-40de-bba6-057e521e700f",
    "memberType" : "OWNER",
    "avatarUrl" : null
  }, {
    "id" : "559e0370-c7e2-4497-b300-d8054e3c4350",
    "name" : "user name -950002",
    "groupId" : "8b79bae9-d0f4-40de-bba6-057e521e700f",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  } ]
} ]

Response fields

Path Type Description

[].id

String

UUID

[].name

String

A notnull name describing this group

[].members

Array

All persons who are members of this group

[].members[].id

String

Unique UUID of this Person

[].members[].accountId

String

Unique UUID the parent Account

[].members[].name

String

Fullname of this Person

[].members[].groupId

String

References the Group

[].members[].memberType

String

MemberType: can be ADMIN, MEMBER, ANALOGUE

[].members[].avatarUrl

String

Optional URL of avatar image

POST /groups/

Creator is automatically the OWNER of the new Group. Owner cannot be removed or lose privileges

Example request

$ curl 'http://localhost:8080/v1/groups' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '{
  "name" : "new group",
  "ownerName" : "Owner"
}'

Request fields

Path Type Description

name

String

New name of Group

ownerName

String

Initial name of Person created for Owner

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 280

{
  "id" : "5ef114ee-681a-474c-a240-109e573070eb",
  "name" : "new group",
  "members" : [ {
    "id" : "05b47246-dd1a-43e5-8e79-b12b9d9ff685",
    "name" : "Owner",
    "groupId" : "5ef114ee-681a-474c-a240-109e573070eb",
    "memberType" : "OWNER",
    "avatarUrl" : null
  } ]
}

PATCH /groups/:id

Name of Group can be changed

Example request

$ curl 'http://localhost:8080/v1/groups/63cf7672-524b-44c9-a457-16fdb118dd38' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '{
  "name" : "newGroupName"
}'

Request fields

Path Type Description

name

String

New name of Group

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 299

{
  "id" : "63cf7672-524b-44c9-a457-16fdb118dd38",
  "name" : "newGroupName",
  "members" : [ {
    "id" : "6e12f5a4-96a4-4b03-9a4b-b518da9d97ee",
    "name" : "email-100@example.com",
    "groupId" : "63cf7672-524b-44c9-a457-16fdb118dd38",
    "memberType" : "OWNER",
    "avatarUrl" : null
  } ]
}

POST /groups/:id/members

Email is used to find an existing Account and create a new Person in this Group. Name and MembershipType must be initialised

Example request

$ curl 'http://localhost:8080/v1/groups/64e69ac1-721b-44b5-8e6a-d7d0f09898ec/members' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '{
  "email" : "email-1070002@example.com",
  "name" : "newGroupName",
  "membershipType" : "ADMIN"
}'

Request fields

Path Type Description

email

String

Email of existing Account to create a new Person for this Group

name

String

Name of new Person

membershipType

String

membershipType, should be MEMBER, ANALOGUE or ADMIN

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 489

{
  "id" : "64e69ac1-721b-44b5-8e6a-d7d0f09898ec",
  "name" : "Group-54",
  "members" : [ {
    "id" : "cc1315d9-3bf2-4da8-8d5e-b803ec1e1f85",
    "name" : "email-106@example.com",
    "groupId" : "64e69ac1-721b-44b5-8e6a-d7d0f09898ec",
    "memberType" : "OWNER",
    "avatarUrl" : null
  }, {
    "id" : "6c2e597e-17f2-4288-8e03-5c65fde4da6e",
    "name" : "newGroupName",
    "groupId" : "64e69ac1-721b-44b5-8e6a-d7d0f09898ec",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  } ]
}

PATCH /groups/:id/members/:personId

Change privilege of a member.

Attention: OWNERS cannot be decreased in privilege.

Example request

$ curl 'http://localhost:8080/v1/groups/4443934f-53e0-45c7-8dc4-a107f6507aea/members/affb123f-66d5-432e-ba94-5860855e9bc9' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '{
  "membershipType" : "ADMIN"
}'

Request fields

Path Type Description

membershipType

String

membershipType, should be MEMBER, ANALOGUE or ADMIN

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 483

{
  "id" : "4443934f-53e0-45c7-8dc4-a107f6507aea",
  "name" : "Group-48",
  "members" : [ {
    "id" : "08d60e33-39b9-4e95-98ad-f57f171c18f7",
    "name" : "email-98@example.com",
    "groupId" : "4443934f-53e0-45c7-8dc4-a107f6507aea",
    "memberType" : "OWNER",
    "avatarUrl" : null
  }, {
    "id" : "affb123f-66d5-432e-ba94-5860855e9bc9",
    "name" : "mmeber2",
    "groupId" : "4443934f-53e0-45c7-8dc4-a107f6507aea",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  } ]
}

DELETE /groups/:id/members/:personId

Delete a non-OWNER of a Group. Note: This endpoint might change to not return a result

Example request

$ curl 'http://localhost:8080/v1/groups/ba163607-ac84-4835-b496-234dbffcd52b/members/975ab0bf-3587-4ce7-baf4-b807862bc061' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*'

Example response

HTTP/1.1 204 No Content
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 294

{
  "id" : "ba163607-ac84-4835-b496-234dbffcd52b",
  "name" : "Group-46",
  "members" : [ {
    "id" : "4dad1c10-cdd7-4c06-a54e-7c81d90fb31e",
    "name" : "email-96@example.com",
    "groupId" : "ba163607-ac84-4835-b496-234dbffcd52b",
    "memberType" : "OWNER",
    "avatarUrl" : null
  } ]
}

GET /groups/

Fetch all Groups of own User.

Example request

$ curl 'http://localhost:8080/v1/groups' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: f6724366-e709-4aa8-8da8-3cd597066c98'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1187

[ {
  "id" : "7232698f-1136-4513-b3e0-49f1c161e525",
  "name" : "Group-43",
  "members" : [ {
    "id" : "52c3ffd0-7a1c-4e3e-acaa-eccb0436047d",
    "name" : "email-92@example.com",
    "groupId" : "7232698f-1136-4513-b3e0-49f1c161e525",
    "memberType" : "OWNER",
    "avatarUrl" : null
  }, {
    "id" : "84c17039-fc7c-444d-a997-49f53b290637",
    "name" : "user name -930002",
    "groupId" : "7232698f-1136-4513-b3e0-49f1c161e525",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  }, {
    "id" : "f6724366-e709-4aa8-8da8-3cd597066c98",
    "name" : "user name -94",
    "groupId" : "7232698f-1136-4513-b3e0-49f1c161e525",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  } ]
}, {
  "id" : "8b79bae9-d0f4-40de-bba6-057e521e700f",
  "name" : "Group-44",
  "members" : [ {
    "id" : "9083045d-8547-4d6e-8f24-42d0b908bc9b",
    "name" : "email-94@example.com",
    "groupId" : "8b79bae9-d0f4-40de-bba6-057e521e700f",
    "memberType" : "OWNER",
    "avatarUrl" : null
  }, {
    "id" : "559e0370-c7e2-4497-b300-d8054e3c4350",
    "name" : "user name -950002",
    "groupId" : "8b79bae9-d0f4-40de-bba6-057e521e700f",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  } ]
} ]

GET /groups/:id

Fetch one Group which own User can access. Endpoint will return 404 for Groups which cannot be found or accessed.

Example request

$ curl 'http://localhost:8080/v1/groups/32a1a6dd-bfc9-4987-bf5b-95d979caa3e8' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 295

{
  "id" : "32a1a6dd-bfc9-4987-bf5b-95d979caa3e8",
  "name" : "Group-57",
  "members" : [ {
    "id" : "9addfc8a-978a-4ead-b6f7-3c8e1fe333b7",
    "name" : "email-110@example.com",
    "groupId" : "32a1a6dd-bfc9-4987-bf5b-95d979caa3e8",
    "memberType" : "OWNER",
    "avatarUrl" : null
  } ]
}

GET /groups/filtered?personId=<UUID>&name=<String>

Filter accessible Groups for own Person and/or Group name

Example request

$ curl 'http://localhost:8080/v1/groups/filtered?personId=75f13de1-5e1d-4519-8bc6-51405e2c003d' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*'

Request parameters

Parameter Description

personId

UUID of Person of own user

name

name (fragment) of an accessible group

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 695

[ {
  "id" : "2ef169b5-b7c4-43cb-ac9b-6e4ee3f419d2",
  "name" : "Group-53",
  "members" : [ {
    "id" : "3051a4e5-19d7-4947-8032-f4e2aa0a0703",
    "name" : "email-106@example.com",
    "groupId" : "2ef169b5-b7c4-43cb-ac9b-6e4ee3f419d2",
    "memberType" : "OWNER",
    "avatarUrl" : null
  }, {
    "id" : "3fc45639-1b60-4a6b-b5e1-48f19ce699ae",
    "name" : "user name -1070002",
    "groupId" : "2ef169b5-b7c4-43cb-ac9b-6e4ee3f419d2",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  }, {
    "id" : "75f13de1-5e1d-4519-8bc6-51405e2c003d",
    "name" : "user name -108",
    "groupId" : "2ef169b5-b7c4-43cb-ac9b-6e4ee3f419d2",
    "memberType" : "ADMIN",
    "avatarUrl" : null
  } ]
} ]

Persons - /persons

GET /persons/:id/avatar.*

Hint: Use Person.avatarUrl to get the suffix.

it will react in three different ways:

  • respond with the Image as content, watch out for content-type and length

  • redirect to another URL, which should be an image

  • respond with a 404 when no usable avatar is found

Example request

$ curl 'http://localhost:8080/v1/persons/9792b6b0-d49b-4065-a576-525304ca42b5/avatar.jpg' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: f67fc071-1a92-4c04-8ea1-37133bf93d06'

GET /persons/:id/public/:key

Public endpoint for Avatars. No need for authentication, but a key has to be provided. As $key, the value of "avatarUrl" has to be used.

Hint: Use Person.avatarUrl to get the key.

it will react in three different ways:

  • respond with the Image as content, watch out for content-type and length

  • redirect to another URL, which should be an image

  • respond with a 404 when no usable avatar is found

Example request

$ curl 'http://localhost:8080/v1/persons/5ac8b4fe-4e50-4ea3-9e58-62cf6f9fd9c8/public/1234.jpg' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/plain'

Example for Redirect of external URL:

Example response

HTTP/1.1 307 Temporary Redirect
Location: avatar.jpg
Accept-Ranges: bytes
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Profile - /profile

GET /profile

Fetch Profile of own user

Example request

$ curl 'http://localhost:8080/v1/profile' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 11ca1fc4-6f77-4197-9ac9-59cdc2c8b2b7'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 181

{
  "id" : "11ca1fc4-6f77-4197-9ac9-59cdc2c8b2b7",
  "name" : "user name -66",
  "groupId" : "8940efed-fae0-4322-8abf-3ad81acdf0d7",
  "memberType" : "ADMIN",
  "avatarUrl" : null
}

Response fields

Path Type Description

id

String

Unique UUID of this Person

accountId

String

Unique UUID the parent Account

name

String

Fullname of this Person

groupId

String

References the Group

memberType

String

MemberType: can be ADMIN, MEMBER, ANALOGUE

avatarUrl

String

Optional URL of avatar image

PATCH /profile

Update Profile of own user: Name and avatarUrl can be changed

Example request

$ curl 'http://localhost:8080/v1/profile' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: f4fd809f-6264-4e33-8f7c-aa595457156d' \
    -d '{
  "name" : "name",
  "avatarUrl" : "https://gitlab.com/uploads/-/system/user/avatar/3209720/avatar.png"
}'

Request fields

Path Type Description

name

String

New Fullname

avatarUrl

String

New URL of avatar

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 236

{
  "id" : "f4fd809f-6264-4e33-8f7c-aa595457156d",
  "name" : "name",
  "groupId" : "cfa2e203-7e84-4732-9485-292dda1236c0",
  "memberType" : "ADMIN",
  "avatarUrl" : "https://gitlab.com/uploads/-/system/user/avatar/3209720/avatar.png"
}

POST /profile

Update Avatar with a new file

Example request

$ curl 'http://localhost:8080/v1/profile/avatar' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 51ca503a-7f87-4e59-bda4-437619c226ab' \
    -F 'file=content'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 192

{
  "id" : "51ca503a-7f87-4e59-bda4-437619c226ab",
  "name" : "email-64@example.com",
  "groupId" : "8940efed-fae0-4322-8abf-3ad81acdf0d7",
  "memberType" : "OWNER",
  "avatarUrl" : "newUrl"
}

Multimedia Management

Albums

GET /albums/own - All my Albums

Example request

$ curl 'http://localhost:8080/v1/albums/own' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 0fbc4c31-dd94-474d-89f3-01c42f9d350e'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1552

[ {
  "id" : "659ce679-f9d7-4765-87b1-654b57900d2d",
  "name" : "filename",
  "ownerId" : "0fbc4c31-dd94-474d-89f3-01c42f9d350e",
  "items" : [ {
    "id" : "a04fadbc-c027-424b-8ded-068cb0ec9e2a",
    "ownerId" : "0fbc4c31-dd94-474d-89f3-01c42f9d350e",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:16.463796Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  }, {
    "id" : "dd4748d8-7b3f-416a-a2f3-24724fe68e33",
    "ownerId" : "0fbc4c31-dd94-474d-89f3-01c42f9d350e",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:16.463827Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  } ],
  "createdAt" : "2023-05-08T15:12:16.463833Z",
  "updatedAt" : null
}, {
  "id" : "0dbfccbb-ec5a-4c49-ae1a-31ef5845c519",
  "name" : "filename",
  "ownerId" : "0fbc4c31-dd94-474d-89f3-01c42f9d350e",
  "items" : [ {
    "id" : "352994cb-53e6-4f17-8707-3dba21e214bf",
    "ownerId" : "0fbc4c31-dd94-474d-89f3-01c42f9d350e",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:16.463839Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  }, {
    "id" : "206719ff-4573-47bd-b8cb-cf8c83de10c4",
    "ownerId" : "0fbc4c31-dd94-474d-89f3-01c42f9d350e",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:16.463842Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  } ],
  "createdAt" : "2023-05-08T15:12:16.463844Z",
  "updatedAt" : null
} ]

Response fields

Path Type Description

[].id

String

UUID

[].ownerId

String

UUID of Owner

[].items

Array

List of contained Multimedias

[].name

String

File to name that file locally

[].createdAt

String

LocalDateTime of Album creation

[].updatedAt

String

LocalDateTime of Album update

[].items[].id

String

UUID

[].items[].ownerId

String

UUID of sending Person

[].items[].createdAt

String

LocalDateTime of Multimedia creation

[].items[].ownerId

String

UUID of Owner

[].items[].filename

String

File to name that file locally

[].items[].type

String

MultimediaType: IMAGE, VIDEO, AUDIO

[].items[].contentType

String

ContentType / MIME type of that file

[].items[].size

Number

Size of file in bytes

[].items[].albumId

String

UUID of parent Album

Create new Album - POST /albums

Example request

$ curl 'http://localhost:8080/v1/albums' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: ab8d0aef-a04c-4f8d-a478-8ff372845a38' \
    -d '{
  "name" : "newname"
}'

Request fields

Path Type Description

name

String

Name of album

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 771

{
  "id" : "0d2a5c50-c733-4473-8050-bf51f33553eb",
  "name" : "newname",
  "ownerId" : "ab8d0aef-a04c-4f8d-a478-8ff372845a38",
  "items" : [ {
    "id" : "47356d9b-5680-4b06-b76a-8141d642fde7",
    "ownerId" : "ab8d0aef-a04c-4f8d-a478-8ff372845a38",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:15.273084Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  }, {
    "id" : "9bcb58db-de00-4a1b-a8c5-beb2912d1ca9",
    "ownerId" : "ab8d0aef-a04c-4f8d-a478-8ff372845a38",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:15.273662Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  } ],
  "createdAt" : "2023-05-08T15:12:15.27367Z",
  "updatedAt" : null
}

GET /albums/shared - All Albums shared with me

Example request

$ curl 'http://localhost:8080/v1/albums/shared' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: e4a02e89-4ed4-4328-963f-4b074bde95b8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1551

[ {
  "id" : "dda36d43-74d3-47ed-b1ed-50e927e28e45",
  "name" : "filename",
  "ownerId" : "60ef66ea-96e8-486c-a97b-98af3f9015b3",
  "items" : [ {
    "id" : "dbcce94c-dd21-48a1-aa25-5518746821c1",
    "ownerId" : "60ef66ea-96e8-486c-a97b-98af3f9015b3",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:15.931767Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  }, {
    "id" : "ab1efc9b-8f85-418c-9953-9fb44ca8ac89",
    "ownerId" : "60ef66ea-96e8-486c-a97b-98af3f9015b3",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:15.931778Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  } ],
  "createdAt" : "2023-05-08T15:12:15.931782Z",
  "updatedAt" : null
}, {
  "id" : "28b59112-bac1-4aff-9253-46bef0013b1c",
  "name" : "filename",
  "ownerId" : "60ef66ea-96e8-486c-a97b-98af3f9015b3",
  "items" : [ {
    "id" : "b1774199-a528-4d22-a6ba-bf086cc67ff6",
    "ownerId" : "60ef66ea-96e8-486c-a97b-98af3f9015b3",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:15.93179Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  }, {
    "id" : "4a66b21c-1f43-4597-8d1f-7649594d6ccb",
    "ownerId" : "60ef66ea-96e8-486c-a97b-98af3f9015b3",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:15.931792Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  } ],
  "createdAt" : "2023-05-08T15:12:15.931794Z",
  "updatedAt" : null
} ]

GET /albums/:id

Example request

$ curl 'http://localhost:8080/v1/albums/549a3fde-6690-4ec1-a7b0-a3d60380b267' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 7899aa85-e6f5-4542-81bd-f529dcb4e277'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 773

{
  "id" : "549a3fde-6690-4ec1-a7b0-a3d60380b267",
  "name" : "filename",
  "ownerId" : "7899aa85-e6f5-4542-81bd-f529dcb4e277",
  "items" : [ {
    "id" : "d2e0c9cc-9b2c-46ad-84cd-15b95edb5269",
    "ownerId" : "7899aa85-e6f5-4542-81bd-f529dcb4e277",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:14.466685Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  }, {
    "id" : "17d890d3-8871-42fe-95f5-b550fd9693cc",
    "ownerId" : "7899aa85-e6f5-4542-81bd-f529dcb4e277",
    "filename" : "filename",
    "contentType" : null,
    "createdAt" : "2023-05-08T15:12:14.466755Z",
    "type" : "IMAGE",
    "size" : null,
    "albumId" : null
  } ],
  "createdAt" : "2023-05-08T15:12:14.467482Z",
  "updatedAt" : null
}

Multimedias

GET /multimedias/own - All my Multimedia

Example request

$ curl 'http://localhost:8080/v1/multimedias/own' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 526

[ {
  "id" : "492ec957-bdf2-412a-9cae-23199d5278b5",
  "ownerId" : "ae615b07-7aec-47a8-830c-508e46cfe5ea",
  "filename" : "filename",
  "contentType" : null,
  "createdAt" : "2023-05-08T15:12:44.724379Z",
  "type" : "IMAGE",
  "size" : null,
  "albumId" : null
}, {
  "id" : "78dc073e-6f32-42ff-888c-18730dcb2b1d",
  "ownerId" : "ae615b07-7aec-47a8-830c-508e46cfe5ea",
  "filename" : "filename",
  "contentType" : null,
  "createdAt" : "2023-05-08T15:12:44.724397Z",
  "type" : "IMAGE",
  "size" : null,
  "albumId" : null
} ]

Response fields

Path Type Description

[].id

String

UUID

[].ownerId

String

UUID of sending Person

[].createdAt

String

LocalDateTime of Multimedia creation

[].ownerId

String

UUID of Owner

[].filename

String

File to name that file locally

[].type

String

MultimediaType: IMAGE, VIDEO, AUDIO

[].contentType

String

ContentType / MIME type of that file

[].size

Number

Size of file in bytes

[].albumId

String

UUID of parent Album

Create & upload new Multimedia - POST /multimedias

File Content must be provided as a MultiPart file in the "form-data" body. ReceiverId and SenderId can be provided as URL request param or also as fields.

Example request

$ curl 'http://localhost:8080/v1/multimedias?ownerId=529799f8-a6e5-4eda-8b77-1ef0df7eaa28' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json, */*' \
    -F 'file=content' \
    -F 'ownerId=529799f8-a6e5-4eda-8b77-1ef0df7eaa28'

Request parameters

Parameter Description

ownerId

UUID of owner - must be your person’s id

albumId

Text to send in message

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 259

{
  "id" : "19172137-686a-414f-9d88-519a29bc6f40",
  "ownerId" : "529799f8-a6e5-4eda-8b77-1ef0df7eaa28",
  "filename" : "newname",
  "contentType" : null,
  "createdAt" : "2023-05-08T15:12:41.525762Z",
  "type" : "IMAGE",
  "size" : null,
  "albumId" : null
}

GET /multimedias/:id

Example request

$ curl 'http://localhost:8080/v1/multimedias/b9242b0c-9f8a-41fa-9c0f-62605e6e5899' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 03fb20d7-a35b-4c72-b7b8-42ae70a49487'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 260

{
  "id" : "b9242b0c-9f8a-41fa-9c0f-62605e6e5899",
  "ownerId" : "03fb20d7-a35b-4c72-b7b8-42ae70a49487",
  "filename" : "filename",
  "contentType" : null,
  "createdAt" : "2023-05-08T15:12:44.185296Z",
  "type" : "IMAGE",
  "size" : null,
  "albumId" : null
}

GET /multimedias/:id/file

Example request

$ curl 'http://localhost:8080/v1/multimedias/5095a254-64cb-4050-8337-7dc52ea92d4f/file' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 05cd5c7a-f68b-4e58-8ee5-bc035b6c2fc5'

Example response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=5095a254-64cb-4050-8337-7dc52ea92d4f.IMAGE
Content-Type: application/json
Accept-Ranges: bytes
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

GET /multimedias/:id/public/:filename

Allowed for unauthenticated usage:

Example request

$ curl 'http://localhost:8080/v1/multimedias/c1e3fa99-8423-4b87-95cc-89e906dbfd7b/public/filename' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/plain'

Example response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=c1e3fa99-8423-4b87-95cc-89e906dbfd7b.IMAGE
Content-Type: application/json
Accept-Ranges: bytes
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

POST /multimedias/:id/file

Example request

$ curl 'http://localhost:8080/v1/multimedias/2ab7017b-600f-4673-b353-b7a448ebf466/file' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json, */*' \
    -F 'file=content'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 259

{
  "id" : "a3785c55-bd00-44a7-97b4-7fb82f1a3f2c",
  "ownerId" : "2b4eacdb-5726-4300-bea6-a96a04ba6fbe",
  "type" : "IMAGE",
  "filename" : "newname",
  "contentType" : null,
  "size" : null,
  "albumId" : null,
  "createdAt" : "2023-05-08T15:12:40.486681Z"
}

NFC Tags & Information

General Structure

Response fields

Path Type Description

id

String

UUID

ownerId

String

UUID of Owner

creatorId

String

UUID of Creator

type

String

NfcInfoType

name

String

File to name that file locally

nfcRef

String

Unique ref id on NTF Tag

linkedPersonId

String

Optional linkedPerson

linkedAlbumId

String

Optional linkedAlbum

createdAt

String

LocalDateTime of NfcInfo creation

updatedAt

String

LocalDateTime of NfcInfo update

Create new NFC - POST /nfc

You can optionally set linked Album OR linked Person. If both are provided, Album will be linked.

Example request

$ curl 'http://localhost:8080/v1/nfcs' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: cab7f5a6-428e-4d50-af62-e51b3ca72a1a' \
    -d '{
  "name" : "newname",
  "nfcRef" : "nfcRef",
  "ownerId" : "cab7f5a6-428e-4d50-af62-e51b3ca72a1a",
  "creatorId" : "cab7f5a6-428e-4d50-af62-e51b3ca72a1a",
  "linkedAlbumId" : null,
  "linkedPersonId" : null
}'

Request fields

Path Type Description

creatorId

String

UUID of creator - must be your person’s id

ownerId

String

UUID of owner - must be the Analogue’s id

name

String

Name of NFC Tag to be shown in UI

nfcRef

String

Unique ref id on NTF Tag

linkedAlbumId

String

Optional Album to link during creation

linkedPersonId

String

Optional Person to link during creation

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 351

{
  "id" : "4770d449-1855-4a69-b507-7009332e45ef",
  "creatorId" : "cab7f5a6-428e-4d50-af62-e51b3ca72a1a",
  "ownerId" : "cab7f5a6-428e-4d50-af62-e51b3ca72a1a",
  "type" : "UNDEFINED",
  "name" : "newname",
  "nfcRef" : "nfcRef",
  "linkedPersonId" : null,
  "linkedAlbumId" : null,
  "createdAt" : "2023-05-08T15:10:04.87188Z",
  "updatedAt" : null
}

Response fields

Path Type Description

id

String

UUID

ownerId

String

UUID of Owner

creatorId

String

UUID of Creator

type

String

NfcInfoType

name

String

File to name that file locally

nfcRef

String

Unique ref id on NTF Tag

linkedPersonId

String

Optional linkedPerson

linkedAlbumId

String

Optional linkedAlbum

createdAt

String

LocalDateTime of NfcInfo creation

updatedAt

String

LocalDateTime of NfcInfo update

Change NFC - PATCH /nfc/:id

You can set Name and ONE OF linked Album OR linked Person. If both are provided, Album will be linked.

Example request

$ curl 'http://localhost:8080/v1/nfcs/1bb59a3c-2fda-428c-bce1-fc6ff4c13643' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 66831233-885a-49dd-b1aa-c0b681094ba6' \
    -d '{
  "name" : "newname",
  "linkedAlbumId" : "0fa88e4f-41f9-4428-b1ee-3395a223c52d",
  "linkedPersonId" : "200c77b6-6e10-4880-8956-fe52405b49e6"
}'

Request fields

Path Type Description

name

String

Name of NFC Tag to be set to

linkedAlbumId

String

UUID of Album - must be in same Group

linkedPersonId

String

UUID of Person - must be in same Group

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 349

{
  "id" : "19c206a2-be05-45e0-9732-82e766e34f7b",
  "creatorId" : "66831233-885a-49dd-b1aa-c0b681094ba6",
  "ownerId" : "42db1840-6310-44d8-b3dc-cd84b733141b",
  "type" : "UNDEFINED",
  "name" : "name",
  "nfcRef" : "nfcRef",
  "linkedPersonId" : null,
  "linkedAlbumId" : null,
  "createdAt" : "2023-05-08T15:10:10.949563Z",
  "updatedAt" : null
}

Response fields

Path Type Description

id

String

UUID

ownerId

String

UUID of Owner

creatorId

String

UUID of Creator

type

String

NfcInfoType

name

String

File to name that file locally

nfcRef

String

Unique ref id on NTF Tag

linkedPersonId

String

Optional linkedPerson

linkedAlbumId

String

Optional linkedAlbum

createdAt

String

LocalDateTime of NfcInfo creation

updatedAt

String

LocalDateTime of NfcInfo update

Get all own NFC - GET /nfc/own

Example request

$ curl 'http://localhost:8080/v1/nfcs/own' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 29e69e76-30e7-44bb-b709-3f0ba7102018'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 704

[ {
  "id" : "7a8f0c85-6488-4717-9562-7c04d7ada2b0",
  "creatorId" : "8babc222-8ff6-4c70-bb1a-a3f9738f0c45",
  "ownerId" : "29e69e76-30e7-44bb-b709-3f0ba7102018",
  "type" : "UNDEFINED",
  "name" : "name",
  "nfcRef" : "nfcRef",
  "linkedPersonId" : null,
  "linkedAlbumId" : null,
  "createdAt" : "2023-05-08T15:10:07.963432Z",
  "updatedAt" : null
}, {
  "id" : "28fc5551-e3bf-49b7-ba2e-3a383b238d6e",
  "creatorId" : "8babc222-8ff6-4c70-bb1a-a3f9738f0c45",
  "ownerId" : "29e69e76-30e7-44bb-b709-3f0ba7102018",
  "type" : "UNDEFINED",
  "name" : "name",
  "nfcRef" : "nfcRef",
  "linkedPersonId" : null,
  "linkedAlbumId" : null,
  "createdAt" : "2023-05-08T15:10:07.963837Z",
  "updatedAt" : null
} ]

Get all created NFC - GET /nfc/created

Example request

$ curl 'http://localhost:8080/v1/nfcs/created' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 20b8c6ca-d769-4c14-a6b7-678f6777c810'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 704

[ {
  "id" : "cd84b4d3-b11c-4e03-bbf3-d424d4084dbc",
  "creatorId" : "20b8c6ca-d769-4c14-a6b7-678f6777c810",
  "ownerId" : "97271781-250c-4052-9ef8-b9682e3f49cd",
  "type" : "UNDEFINED",
  "name" : "name",
  "nfcRef" : "nfcRef",
  "linkedPersonId" : null,
  "linkedAlbumId" : null,
  "createdAt" : "2023-05-08T15:10:10.050759Z",
  "updatedAt" : null
}, {
  "id" : "8672481a-7d81-4fe3-874e-98aa9296d769",
  "creatorId" : "20b8c6ca-d769-4c14-a6b7-678f6777c810",
  "ownerId" : "97271781-250c-4052-9ef8-b9682e3f49cd",
  "type" : "UNDEFINED",
  "name" : "name",
  "nfcRef" : "nfcRef",
  "linkedPersonId" : null,
  "linkedAlbumId" : null,
  "createdAt" : "2023-05-08T15:10:10.050805Z",
  "updatedAt" : null
} ]

Get one NFC - GET /nfc/:id

Example request

$ curl 'http://localhost:8080/v1/nfcs/e187dd2b-c7d0-4a36-82ba-3ba244430bdb' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 694ca5e8-fd41-4c4e-9900-e25769084b26'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 349

{
  "id" : "e187dd2b-c7d0-4a36-82ba-3ba244430bdb",
  "creatorId" : "51223445-28d1-46cd-a60b-f458cdba465b",
  "ownerId" : "694ca5e8-fd41-4c4e-9900-e25769084b26",
  "type" : "UNDEFINED",
  "name" : "name",
  "nfcRef" : "nfcRef",
  "linkedPersonId" : null,
  "linkedAlbumId" : null,
  "createdAt" : "2023-05-08T15:10:09.076942Z",
  "updatedAt" : null
}

Delete one NFC - DELETE /nfc/:id

Example request

$ curl 'http://localhost:8080/v1/nfcs/17b8abbb-8f9c-4362-8bfc-f6f474398e17' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 6ecc646f-46e7-46fe-9561-395fe7129541'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Sendables

All Sendables behave similar and share a big amount of code. See the first example of Sendable endpoints used on Message for further information.

As a multi-user platform, amigo-platform needs to know which Person is meant to be the owner of the request.

Every idempotent sendable request takes an optional "personId" parameter:

Parameter Description

personId?

UUID of own Person to this request

Messages

Create new Message - POST /messages

Example request

$ curl 'http://localhost:8080/v1/messages?receiverId=b19592e7-cd06-4700-9062-4affb6e01f86&senderId=357b6549-2b79-401a-a2b8-90ea9f78a929' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json, */*' \
    -F 'text=expected' \
    -F 'text=expected' \
    -F 'receiverId=b19592e7-cd06-4700-9062-4affb6e01f86' \
    -F 'senderId=357b6549-2b79-401a-a2b8-90ea9f78a929'

Request parameters

Parameter Description

receiverId

UUID of receiver

senderId

UUID of sender - must be your id

text

message text

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 324

{
  "id" : "06de1f1c-c25f-419c-b35c-b59f283f7059",
  "senderId" : "357b6549-2b79-401a-a2b8-90ea9f78a929",
  "receiverId" : "b19592e7-cd06-4700-9062-4affb6e01f86",
  "text" : "expected",
  "multimedia" : null,
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:14.198103Z",
  "sentAt" : null,
  "retrievedAt" : null
}

Response fields

Path Type Description

id

String

UUID

senderId

String

UUID of sending Person

receiverId

String

UUID of receiving Person

text

String

Text of this message

multimediaId

String

Optional UUID of appended Multimedia

multimedia

Object

Optional appended Multimedia

createdAt

String

LocalDateTime of message creation

sentAt

String

LocalDateTime of message sending process

retrievedAt

String

LocalDateTime of message marked as retrieved

Filter Messages - GET /messages/filter?receiverId=<UUID>&senderId=<UUID>

Example request

$ curl 'http://localhost:8080/v1/messages/filter?receiverId=f2b5cb1f-db67-4415-aa30-271551f8ef50&senderId=9f68ca29-754d-4e04-8ddc-690f9ce6d8ed' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 600

[ {
  "id" : "f94c15c6-4a5c-4894-b7cc-7926f286ace8",
  "senderId" : "9f68ca29-754d-4e04-8ddc-690f9ce6d8ed",
  "receiverId" : "f2b5cb1f-db67-4415-aa30-271551f8ef50",
  "text" : "text",
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:15.394618Z",
  "sentAt" : null,
  "retrievedAt" : null
}, {
  "id" : "1f29a856-f717-4e84-9a0b-cc43d1e46e23",
  "senderId" : "9f68ca29-754d-4e04-8ddc-690f9ce6d8ed",
  "receiverId" : "f2b5cb1f-db67-4415-aa30-271551f8ef50",
  "text" : "text",
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:15.394685Z",
  "sentAt" : null,
  "retrievedAt" : null
} ]

GET /messages/received - All my retrieved

Example request

$ curl 'http://localhost:8080/v1/messages/received' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 551b5132-3d6f-49a0-abcb-b4f34a37245d'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 600

[ {
  "id" : "a7ef76a4-d2a0-4323-bacd-523e256b4a14",
  "senderId" : "31a34236-da62-414c-b47b-1df0ca0819bd",
  "receiverId" : "551b5132-3d6f-49a0-abcb-b4f34a37245d",
  "text" : "text",
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:09.734988Z",
  "sentAt" : null,
  "retrievedAt" : null
}, {
  "id" : "b1894f55-aafd-42ab-bc90-07a6de4543b8",
  "senderId" : "de1c0ee7-3ac0-4704-8834-f05b8257941f",
  "receiverId" : "551b5132-3d6f-49a0-abcb-b4f34a37245d",
  "text" : "text",
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:09.735049Z",
  "sentAt" : null,
  "retrievedAt" : null
} ]

GET /messages/sent - All my sent

Example request

$ curl 'http://localhost:8080/v1/messages/sent' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: b2a2563f-dcc4-43bf-8781-927be25249b9'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 600

[ {
  "id" : "774cf43e-f036-418d-812b-2a60e328a289",
  "senderId" : "b2a2563f-dcc4-43bf-8781-927be25249b9",
  "receiverId" : "75c7374b-30e1-491f-a18a-60e11ccdc597",
  "text" : "text",
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:14.821301Z",
  "sentAt" : null,
  "retrievedAt" : null
}, {
  "id" : "08eee11b-bbe5-4a10-b05c-444a658e7f34",
  "senderId" : "b2a2563f-dcc4-43bf-8781-927be25249b9",
  "receiverId" : "856e068b-01f3-423d-b40c-f9a96e39528d",
  "text" : "text",
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:14.821382Z",
  "sentAt" : null,
  "retrievedAt" : null
} ]

GET /messages/:id

Example request

$ curl 'http://localhost:8080/v1/messages/53881550-5ac1-466f-b1e7-930a2eb64abf' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: f8347489-f81e-46d9-acd6-913977f67d1e'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 319

{
  "id" : "53881550-5ac1-466f-b1e7-930a2eb64abf",
  "senderId" : "f261c246-80cc-4fcb-aad5-aa8f722231e4",
  "receiverId" : "f8347489-f81e-46d9-acd6-913977f67d1e",
  "text" : "text",
  "multimedia" : null,
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:13.67758Z",
  "sentAt" : null,
  "retrievedAt" : null
}

PATCH /messages/:id/set-retrieved - Set Message as "retrieved"

Example request

$ curl 'http://localhost:8080/v1/messages/c6dc98d2-64d8-4795-a70b-bbdb575805e1/set-retrieved' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '"49ccf74d-2969-412c-808b-7d69b219fb0f"'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 345

{
  "id" : "c6dc98d2-64d8-4795-a70b-bbdb575805e1",
  "senderId" : "ba7fada0-2ed9-4d99-a2c2-40a5edc1437f",
  "receiverId" : "49ccf74d-2969-412c-808b-7d69b219fb0f",
  "text" : "text",
  "multimedia" : null,
  "multimediaId" : null,
  "createdAt" : "2023-05-08T15:11:11.051143Z",
  "sentAt" : null,
  "retrievedAt" : "2023-05-08T15:11:11.051118Z"
}

Calls

Create & start new Jitsi calls - POST /calls

File Content must be provided as a MultiPart file in the "form-data" body. ReceiverId and SenderId can be provided as URL request param or also as fields.

Note: The kind-of-secret JWT Jitsi token is only set by create, get-one, and accept.

Example request

$ curl 'http://localhost:8080/v1/calls?receiverId=cc9fb175-9aa0-4653-899f-611cab8304a3&personId=d5cb7fb3-9901-45d9-be4f-49b773246e09&callType=VIDEO' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*'

Request parameters

Parameter Description

receiverId

UUID of receiver

personId

UUID of sender - must be your id

callType

VIDEO or AUDIO

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 370

{
  "id" : "1c7a734d-8066-4372-ac1e-98aec53ca19e",
  "senderId" : "d5cb7fb3-9901-45d9-be4f-49b773246e09",
  "receiverId" : "cc9fb175-9aa0-4653-899f-611cab8304a3",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CALLING",
  "token" : "sender",
  "createdAt" : "2023-05-08T15:11:43.94937Z",
  "sentAt" : null,
  "retrievedAt" : null
}

Response fields

Path Type Description

id

String

UUID

senderId

String

UUID of sending Person

receiverId

String

UUID of receiving Person

callType

String

VIDEO or AUDIO

callState

String

CallState: CREATED, CALLING, CANCELLED, DENIED, ACCEPTED, STARTED, FINISHED, TIMEOUT

startedAt

String

LocalDateTime of start

finishedAt

String

LocalDateTime of finish

createdAt

String

LocalDateTime of call creation

sentAt

String

LocalDateTime of call sending process

retrievedAt

String

LocalDateTime of call marked as retrieved

token

String

Jitsi JWT Token to authenticate person

Filter calls - GET /calls/filter?receiverId=<UUID>&senderId=<UUID>

Example request

$ curl 'http://localhost:8080/v1/calls/filter?receiverId=2b9290d6-5822-43a6-b6fc-55794a02255f&senderId=02780b55-c23f-4b7e-b9ff-734d4017ed80' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 704

[ {
  "id" : "4b790056-8d5e-4857-b794-8a77439c4724",
  "senderId" : "02780b55-c23f-4b7e-b9ff-734d4017ed80",
  "receiverId" : "2b9290d6-5822-43a6-b6fc-55794a02255f",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CALLING",
  "createdAt" : "2023-05-08T15:11:48.614491Z",
  "sentAt" : null,
  "retrievedAt" : null
}, {
  "id" : "9e27e58e-73f6-497f-a612-bd18a09c5528",
  "senderId" : "02780b55-c23f-4b7e-b9ff-734d4017ed80",
  "receiverId" : "2b9290d6-5822-43a6-b6fc-55794a02255f",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CALLING",
  "createdAt" : "2023-05-08T15:11:48.614515Z",
  "sentAt" : null,
  "retrievedAt" : null
} ]

GET /calls/received - All my retrieved Calls

Example request

$ curl 'http://localhost:8080/v1/calls/received' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: 61d27cf6-626b-49e6-ab70-d9489c26f141'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 703

[ {
  "id" : "e14639e4-c37b-4924-9a0a-ca38bad2f30b",
  "senderId" : "bbbc1e3f-60d5-4fde-8e37-c420d921abb9",
  "receiverId" : "61d27cf6-626b-49e6-ab70-d9489c26f141",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CALLING",
  "createdAt" : "2023-05-08T15:11:47.482837Z",
  "sentAt" : null,
  "retrievedAt" : null
}, {
  "id" : "b53b41b4-9bad-4e84-b65f-c54166bf4111",
  "senderId" : "bbbc1e3f-60d5-4fde-8e37-c420d921abb9",
  "receiverId" : "61d27cf6-626b-49e6-ab70-d9489c26f141",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CALLING",
  "createdAt" : "2023-05-08T15:11:47.48285Z",
  "sentAt" : null,
  "retrievedAt" : null
} ]

GET /calls/sent - All my started Calls

Example request

$ curl 'http://localhost:8080/v1/calls/sent' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: cbac3005-fa44-49f4-b510-daf87736d0cf'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 703

[ {
  "id" : "380cac08-5b32-4b30-9bc1-280a76a6b7c3",
  "senderId" : "cbac3005-fa44-49f4-b510-daf87736d0cf",
  "receiverId" : "6e0b972b-6937-4e89-ab2b-9773f2259b1d",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CALLING",
  "createdAt" : "2023-05-08T15:11:50.69362Z",
  "sentAt" : null,
  "retrievedAt" : null
}, {
  "id" : "3c9277ad-e2c6-460b-8a0e-05fbc945050c",
  "senderId" : "cbac3005-fa44-49f4-b510-daf87736d0cf",
  "receiverId" : "6e0b972b-6937-4e89-ab2b-9773f2259b1d",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CALLING",
  "createdAt" : "2023-05-08T15:11:50.693645Z",
  "sentAt" : null,
  "retrievedAt" : null
} ]

GET /calls/:id

Note: The kind-of-secret JWT Jitsi token is only set by create, get-one, and accept.

Example request

$ curl 'http://localhost:8080/v1/calls/26c383b6-7f1c-4095-b5bf-55fa4a41865c' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -H 'Amigo-Person-Id: a61051af-2c4c-4117-9e2c-32b6379ba35e'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 373

{
  "id" : "26c383b6-7f1c-4095-b5bf-55fa4a41865c",
  "senderId" : "3f9baf4a-7c8f-4778-96d4-63d9ffd0b29f",
  "receiverId" : "a61051af-2c4c-4117-9e2c-32b6379ba35e",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CALLING",
  "token" : "receiver",
  "createdAt" : "2023-05-08T15:11:50.257561Z",
  "sentAt" : null,
  "retrievedAt" : null
}

PATCH /calls/:id/accept - Accept a call

Can be called by callee to accept an incoming call. Note: The kind-of-secret JWT Jitsi token is only set by create, get-one, and accept.

Example request

$ curl 'http://localhost:8080/v1/calls/6f875a96-1eab-4d20-9619-62a305a69977/accept' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '"467f7ce8-d9b5-414a-83bd-3f925538b409"'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 422

{
  "id" : "6f875a96-1eab-4d20-9619-62a305a69977",
  "senderId" : "82c48d96-8ae2-451a-b9cf-dcdd7d1449bc",
  "receiverId" : "467f7ce8-d9b5-414a-83bd-3f925538b409",
  "callType" : "VIDEO",
  "startedAt" : "2023-05-08T15:11:49.559822Z",
  "finishedAt" : null,
  "callState" : "ACCEPTED",
  "token" : "receiver",
  "createdAt" : "2023-05-08T15:11:49.5099Z",
  "sentAt" : null,
  "retrievedAt" : "2023-05-08T15:11:49.559815Z"
}

PATCH /calls/:id/cancel - Cancel an outgoing own call

Can be called by caller to cancel an outgoing own call.

Example request

$ curl 'http://localhost:8080/v1/calls/2eef2597-a8f9-44e2-ba59-da63fa5e8b45/cancel' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '"a93caadf-76d6-47d6-a77f-15696c3224d2"'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 351

{
  "id" : "2eef2597-a8f9-44e2-ba59-da63fa5e8b45",
  "senderId" : "a93caadf-76d6-47d6-a77f-15696c3224d2",
  "receiverId" : "204ae7e1-5de5-4051-bcfb-06fa4a5d76f9",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "CANCELLED",
  "createdAt" : "2023-05-08T15:11:48.060157Z",
  "sentAt" : null,
  "retrievedAt" : null
}

PATCH /calls/:id/deny - Denies an incoming call

Can be called by callee to deny an incoming call.

Example request

$ curl 'http://localhost:8080/v1/calls/79925778-f932-44bc-8c48-9ff6fe9ec558/deny' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '"79b74b9d-7b7c-418c-96cb-7134626883ec"'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 371

{
  "id" : "79925778-f932-44bc-8c48-9ff6fe9ec558",
  "senderId" : "3f8be3ef-a680-4277-ab17-8769ded49205",
  "receiverId" : "79b74b9d-7b7c-418c-96cb-7134626883ec",
  "callType" : "VIDEO",
  "startedAt" : null,
  "finishedAt" : null,
  "callState" : "DENIED",
  "createdAt" : "2023-05-08T15:11:46.92077Z",
  "sentAt" : null,
  "retrievedAt" : "2023-05-08T15:11:46.97295Z"
}

PATCH /calls/:id/finish - Finishes an incoming/outgoing call

Can be called by both parties to finish a running call.

Example request

$ curl 'http://localhost:8080/v1/calls/5097c71d-cb0b-4732-9049-4e3c19916aea/finish' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, */*' \
    -d '"d4261079-3c1c-425f-8310-151805fefa07"'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 425

{
  "id" : "5097c71d-cb0b-4732-9049-4e3c19916aea",
  "senderId" : "dd0e6e5e-96c6-4262-9bea-eb1346c08ca7",
  "receiverId" : "d4261079-3c1c-425f-8310-151805fefa07",
  "callType" : "VIDEO",
  "startedAt" : "2023-05-08T15:11:42.240362Z",
  "finishedAt" : "2023-05-08T15:11:43.240395Z",
  "callState" : "FINISHED",
  "createdAt" : "2023-05-08T15:11:43.131266Z",
  "sentAt" : null,
  "retrievedAt" : "2023-05-08T15:11:43.240255Z"
}