Presence - Huddle/huddle-apis GitHub Wiki

Summary

The Presence API is a representation of user presentities within Huddle.

Status

Operation
Retrieve Audit Entry
Create Presence
Retrieve Presence by User
Retrieve Presence by Users
Retrieve Presence by Team
Retrieve Presence by Workspace
Update Presence
Delete Presence

Operations

Retrieve Audit Entry

This API is to get the audit list based on the given User. The audit lists will be used to verify the previous actions performed by the given User.

Example

Example request, asking for the Audit Entry for User with ID 123:

GET /presence/123/audits HTTP/1.1 
Accept: application/json 
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK 
Content-Type: application/json

{
  "links": [ 
    { 
      "rel": "self", 
      "href": "..." 
    },
    { 
      "rel": "parent", 
      "href": "..." 
    }
  ],
  "audits": [ 
    { 
      "auditType": "create",
      "timeStamp": "2022-04-20T16:30:29+00:00", 
      "context": "{'id':999}"
    },
    {
      ...
    }
  ]
}

Response Properties

Name	Description
auditType	The type of the action performed by the User (eg. create, update, delete)
context	The details of the action performed by the User (eg. The newly created Presence Id, the updated message of Presence)

Response Link relations

Name	Description	Methods
self	The URI of the Audits	GET
parent	The URI of the User	GET
first	The URI to move to first page	GET
previous	The URI to move to previous page	GET
next	The URI to move to next page	GET

Other Responses

Case	Response Code	Error Code
No User provided	400 Bad Request	UserNotProvided
Invalid authorization token	401 Unauthorized	AccessTokenInvalid
User does not exist	404 Not Found	UserNotFound

Create Presence

This API will be called when users turn on their OOO setting. This API will not invalidate the previous Presence data and will create a new instance of Presence instead.

Example

Example request:

POST /presence/create HTTP/1.1 
Content-Type: application/json 
Authorization: Bearer frootymcnooty/vonbootycherooty

{ 
  "isActive": true, 	
  "startDate": "2022-04-19T16:30:29+00:00", 	
  "endDate": "2022-04-20T16:30:29+00:00", 
  "message": "out of office" 
}

Request Payload Description

Field	Data Type	Required	Example
isActive	Boolean	Required	true
startDate	DateTimeOffset	Optional	"2022-08-19T16:30:29+00:00"
endDate	DateTimeOffset	Optional	"2022-08-19T16:30:29+00:00"
message	String	Optional	"John Doe is OOO."

Example response, Presence with ID 456 is created:

HTTP/1.1 201 Created
Content-Type: application/json
Content-Location: .../presence/456

{
  "links": [
    { 
      "rel": "self", 
      "href": "..."
    },
    { 
      "rel": "user", 
      "href": "..." 
    }
  ],
  "isActive": true, 
  "startDate": "2022-04-19T16:30:29+00:00", 
  "endDate": "2022-04-20T16:30:29+00:00", 
  "message": "out of office"
}

Response Link relations

Name	Description	Methods
self	The URI of the newly created Presence	GET
user	The URI of the User	GET

Other Responses

Case	Response Code	Error Code
Date values invalid	400 Bad Request	DateInvalid
Date range invalid	400 Bad Request	DateRangeInvalid
Message exceeds 280 characters	400 Bad Request	MessageLengthLimitExceeded
Invalid authorization token	401 Unauthorized	AccessTokenInvalid

Retrieve Presence by User

This API is designed to allow the user to able to retrieve the Presence data for a single User. This API can only be called by the User themselves when they are trying to view/change their own OOO setting. The User will need to have a valid authentication token to call this API.

Example

Example request, asking for the Presence for User with ID 123:

GET /presence/123 HTTP/1.1 
Accept: application/json  
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK 
Content-Type: application/json

{ 
  "presenceEntities": [
    { 
      "links": [
        { 
          "rel": "user", 
          "href": "..."
        },
        { 
          "rel": "presence", 
          "href": "..."
        }
      ],
      "isActive": true, 
      "startDate": "2022-04-19T16:30:29+00:00", 
      "endDate": "2022-04-20T16:30:29+00:00", 
      "message": "out of office" 
    }, 
    {
      ...
    }
  ]
}

Response Link relations

Name	Description	Methods
self	The URI of the Presence of the User	GET

Other Responses

Case	Response Code	Error Code
No User provided	400 Bad Request	UserNotProvided
Invalid authorization token	401 Unauthorized	AccessTokenInvalid
User does not exist	404 Not Found	UserNotFound

Retrieve Presence by Users

This API is designed to allow the user to retrieve the list of Presence data based on the given list of Users and a range of dates. This API can be called by the User who has access/permission to view a list of Users.

Example

Example request:

POST /presence HTTP/1.1 
Accept: application/json 
Content-Type: application/json 
Authorization: Bearer frootymcnooty/vonbootycherooty

{ 
  "startDate": "2022-04-19T16:30:29+00:00", 
  "endDate": "2022-04-20T16:30:29+00:00", 
  "links": [ 
    { 
      "rel": "user", 
      "href": "..." 
    },
    {
      ...
    }
  ]
}

Example response:

HTTP/1.1 200 OK 
Content-Type: application/json

{
  "links": [
    { 
      "rel": "self", 
      "href": "..." 
    } 
  ],
  "presenceEntities": [
    { 
      "links": [
        { 
          "rel": "user", 
          "href": "..."
        },
        { 
          "rel": "presence", 
          "href": "..."
        }
      ],
      "isActive": true, 
      "startDate": "2022-04-19T16:30:29+00:00", 
      "endDate": "2022-04-20T16:30:29+00:00", 
      "message": "out of office" 
    }, 
    {
      ...
    }
  ]
}

Response Link relations

Name	Description	Methods
self	The URI of the Presences	GET
user	The URI of the User	GET
presence	The URI of the Presence	GET
first	The URI to move to first page	GET
previous	The URI to move to previous page	GET
next	The URI to move to next page	GET

Other Responses

Case	Response Code	Error Code
No User provided	400 Bad Request	UserNotProvided
Date values invalid	400 Bad Request	DateInvalid
Date range invalid	400 Bad Request	DateRangeInvalid
Invalid authorization token	401 Unauthorized	AccessTokenInvalid
User does not exist	404 Not Found	UserNotFound

Retrieve Presence by Team

This API is designed to allow the user to able to retrieve the list of Presence data based on the given Team and a range of dates. This API can be called by User who is able to view the Team. (eg. The Team creator, the Team members) Firstly, the User must be authenticated by using the authentication token. Then, the User will go through authorization process to ensure the User has the sufficient permission to access the Team information to call this API.

Example

Example request, asking for the Presence for Team with ID 123:

POST /presence/teams/123 HTTP/1.1 
Accept: application/json 
Content-Type: application/json 
Authorization: Bearer frootymcnooty/vonbootycherooty

{ 
  "startDate": "2022-04-19T16:30:29+00:00", 
  "endDate": "2022-04-20T16:30:29+00:00", 
  "links": [ 
    { 
      "rel": "team", 
      "href": "..." 
    }
  ]
}

Example response:

HTTP/1.1 200 OK 
Content-Type: application/json

{
  "links": [
    { 
      "rel": "self", 
      "href": "..." 
    } 
  ],
  "presenceEntities": [
    { 
      "links": [
        { 
          "rel": "user", 
          "href": "..."
        },
        { 
          "rel": "presence", 
          "href": "..."
        }
      ],
      "isActive": true, 
      "startDate": "2022-04-19T16:30:29+00:00", 
      "endDate": "2022-04-20T16:30:29+00:00", 
      "message": "out of office" 
    }, 
    {
      ...
    }
  ]
}

Response Link relations

Name	Description	Methods
self	The URI of the Team	GET
user	The URI of the User	GET
presence	The URI of the Presence	GET
first	The URI to move to first page	GET
previous	The URI to move to previous page	GET
next	The URI to move to next page	GET

Other Responses

Case	Response Code	Error Code
No Team provided	400 Bad Request	TeamNotProvided
Date values invalid	400 Bad Request	DateInvalid
Date range invalid	400 Bad Request	DateRangeInvalid
Invalid authorization token	401 Unauthorized	AccessTokenInvalid
Any permission errors	403 Forbidden	InsufficientPermissions
User is not a member of the Team	403 Forbidden	TeamMembershipRequired
Team is deleted	403 Forbidden	TeamDeleted
No valid Team provided	404 Not Found	TeamNotFound

Retrieve Presence by Workspace

This API is designed to allow the user to able to retrieve the list of Presence data based on the given Workspace and a range of dates. This API can be called by User who is able to view the Workspace. (eg. The Workspace creator, the Workspace members) Firstly, the User must be authenticated by using the authentication token. Then, the User will go through authorization process to ensure the User has the sufficient permission to access the Workspace information to call this API.

Example

Example request, asking for the Presence for Workspace with ID 123:

POST /presence/workspace/{workspaceId} HTTP/1.1 
Accept: application/json 
Content-Type: application/json 
Authorization: Bearer frootymcnooty/vonbootycherooty

{ 
  "startDate": "2022-04-19T16:30:29+00:00", 
  "endDate": "2022-04-20T16:30:29+00:00", 
  "links": [ 
    { 
      "rel": "workspace", 
      "href": "..." 
    }
  ]
}

Example response:

HTTP/1.1 200 OK 
Content-Type: application/json

{
  "links": [
    { 
      "rel": "self", 
      "href": "..." 
    } 
  ],
  "presenceEntities": [
    { 
      "links": [
        { 
          "rel": "user", 
          "href": "..."
        },
        { 
          "rel": "presence", 
          "href": "..."
        }
      ],
      "isActive": true, 
      "startDate": "2022-04-19T16:30:29+00:00", 
      "endDate": "2022-04-20T16:30:29+00:00", 
      "message": "out of office" 
    }, 
    {
      ...
    }
  ]
}

Response Link relations

Name	Description	Methods
self	The URI of the Workspace	GET
user	The URI of the User	GET
presence	The URI of the Presence	GET
first	The URI to move to first page	GET
previous	The URI to move to previous page	GET
next	The URI to move to next page	GET

Other Responses

Case	Response Code	Error Code
No Workspace provided	400 Bad Request	WorkspaceNotProvided
Date values invalid	400 Bad Request	DateInvalid
Date range invalid	400 Bad Request	DateRangeInvalid
Invalid authorization token	401 Unauthorized	AccessTokenInvalid
Any permission errors	403 Forbidden	InsufficientPermissions
User is not a member of the Workspace	403 Forbidden	WorkspaceMembershipRequired
Workspace is archived	403 Forbidden	WorkspaceArchived
Workspace is locked	403 Forbidden	WorkspaceLocked
Workspace is deleted	403 Forbidden	WorkspaceDeleted
No valid Workspace provided	404 Not Found	WorkspaceNotFound

Update Presence

This API will be called to update the details within the OOO setting for a User. (eg. isActive , startDate, endDate, message) If the User or Presence is invalid, no Presence will be updated. Only the User(owner) can update the OOO setting by themselves with a valid authentication token.

Example

Example request, updating Presence with ID 456 for User with ID 123:

PUT /presence/123/456 HTTP/1.1 
Accept: application/json 
Content-Type: application/json 
Authorization: Bearer frootymcnooty/vonbootycherooty

{ 
  "isActive": true, 
  "startDate": "2022-04-19T16:30:29+00:00", 
  "endDate": "2022-04-20T16:30:29+00:00", 
  "message": "out of office" 
}

Example response:

HTTP/1.1 200 OK 
Content-Type: application/json 
Content-Location: /presence/123/456

{ 
  "links": [
    { 
      "rel": "self", 
      "href": "..." 
    },
    { 
      "rel": "user", 
      "href": "..."
    },
    { 
      "rel": "presence", 
      "href": "..."
    }
  ],
  "isActive": true, 
  "startDate": "2022-04-19T16:30:29+00:00", 
  "endDate": "2022-04-20T16:30:29+00:00", 
  "message": "out of office" 
}

Response Link relations

Name	Description	Methods
self	The URI of the updating Presence	GET
user	The URI of the User	GET
presence	The URI of the Presence	GET

Other Responses

Case	Response Code	Error Code
Invalid date data provided	400 Bad Request	PresenceDateInvalid
Invalid authorization token	401 Unauthorized	AccessTokenInvalid
Insufficient permission	403 Forbidden	InsufficientPermission
No valid User provided	404 Not Found	UserNotFound
No valid Presence provided	404 Not Found	PresenceNotFound

Delete Presence

This API will be called to remove the current OOO status for a User.

Example

Example request, deleting Presence with ID 456 for User with ID 123:

DELETE /presence/123/456 HTTP/1.1 
Content-Type: application/json 
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 204 No Content

Other Responses

Case	Response Code	Error Code
No User provided	400 Bad Request	UserNotProvided
No Presence provided	400 Bad Request	PresenceNotProvided
Invalid authorization token	401 Unauthorized	AccessTokenInvalid
Insufficient permission	403 Forbidden	InsufficientPermission
User does not exist	404 Not Found	UserNotFound
Presence does not exist	404 Not Found	PresenceNotFound