Team Demerzel Events API Documentation

Introduction

Welcome to team Demerzel Event API documentation. Our API is designed to empower your mobile app with the ability to seamlessly manage events, groups, and user interactions. With this API, you can effortlessly create, read, update, and delete events, allowing your users to stay engaged and informed. Additionally, users can create groups, subscribe to their favorite communities, leave comments on events, and express their interest in attending. Dive into our comprehensive documentation to unlock the full potential of enhancing user experiences with event management and community engagement in your app.

API Usage and Features

How to Call the API

The API can be accessed via HTTP requests. It exposes endpoints for various CRUD operations on events, users and groups. An Authentication Bearer Token needs to be set in the request header, to get the JWT token, read how to Authenticate in the next section.

local Host: localHost:5005/
Current (Active) Host: https://api-s65g.onrender.com/
API Base Path: /api

Authorization : Bearer <replace_with_jwt_token>

Authenticating to the API

The API supports the Google OAuth Authentication Workflow:
To initialize the OAuthentication workflow, the endpoint: GET /oauth/initialize, should be accessed, upon success a redirection_url is sent along with the response. If successful, the JWT Token to be used in subsequent request header should be gotten from the response body.

Path: {host}/oauth/initialize

Sample Request

Request URL: {host}/oauth/initialize
Request Method: GET

Sample Response

Status Code: 200

Body:

{
   "status": "success"
   "data": {
      "redirectUrl": "https://accounts.google.com/o/oauth2/auth?client_id=1024268478019-v7ebrdubfni6qsvtpiicv9eb2le6m4al.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fapi-s65g.onrender.com%2Foauth%2Fcallback&response_type=code&scope=openid+profile+email&state=somerandomoauthstri"
   },
   "message": "Authentication initialized",
}

After Oauth Redirection

Response Body:

{
   "status":"success",
   "data":{"token": "jwt_token"},
   "message":"Authentication successful"
}

Security Definitions

{
   "securityDefinitions": {
      "Bearer": {
         "type": "apiKey",
         "name": "Authorization",
         "in": "header",
         "description": "Enter your Bearer token in the format: Bearer <token>"
      }
   }
}

API Endpoints

API Health

GET /health

Sample Request URL: {host}/health

Response:
Status Code: 200
Body:

{
   "data": null,
   "message": "Team Demerzel Events API",
   "status": "success"
}

Authentication

GET /oauth/initialize
- Summary: Initialize the Oauth workflow
- Despcription: Authenticate a user using Google's Oauth and get a JWT token for subsequent requests.
  NB: Read the section above to get more information

Groups

POST /api/groups

Summary: Create a group
Description: Creates a new group and returns it, supply the name of the group in the request body.
Sample Request URL: {host}/api/groups
Parameters:
Body:
```
{
"name": "group_name"
}
```

Responses:
Status Code: 201
Body:

{
   "status": "success",
   "data": {
      "id": "a2218d8f-4cdb-4114-a847-4cf8fcbd2e54",
      "name": "group_name",
      "created_at": "2023-09-20T18:28:42.523+01:00",
      "updated_at": "2023-09-20T18:28:42.523+01:00",
      "members": null
   },
   "message": "Group created successfully"
}

Status Code: 400
Body:

{
   "status": "error",
   "message": "Invalid request body format",
   "data": null
}

PUT /api/groups/{id}

Summary: Update a group
Description: Update an existing group by ID, supply the new name of the group in the request body.
Sample Request URL: {host}/api/groups/9d8be7c8-d2f7-4e4a-8897-9a08e5a18340
Parameters:
Body:
```
{
"name": "new_group_name"
}
```

Response:
Status Code: 200
Body:

{
   "data": {
      "id": "9d8be7c8-d2f7-4e4a-8897-9a08e5a18340",
      "name": "new_group_name",
      "created_at": "2023-09-22T05:09:44.999Z",
      "updated_at": "2023-09-22T05:15:07.97Z",
      "members": null
   },
   "message": "Group updated successfully",
   "status": "success"
}

GET /api/groups/{id}

Summary: Get a group by Id
Description: Fetch a group details with Id
Sample Request Url: {host}/api/groups/bcbb8231-e97d-461e-aa95-e2c426b68b28

Response:
Status Code: 200 Body:

{
   "data": {
      "id": "bcbb8231-e97d-461e-aa95-e2c426b68b28",
      "name": "My Group",
      "created_at": "2023-09-22T09:34:44.376Z",
      "updated_at": "2023-09-22T09:34:44.376Z",
      "members": [
            {
               "id": "a750e6c1-50e5-4ba3-84fc-73dbbb684acc",
               "user_id": "6be00466-af9f-444c-81bc-969d575342be",
               "group_id": "bcbb8231-e97d-461e-aa95-e2c426b68b28",
               "created_at": "2023-09-22T09:55:59.673Z",
               "updated_at": "2023-09-22T09:55:59.673Z",
               "user": {
                  "id": "6be00466-af9f-444c-81bc-969d575342be",
                  "name": "user_name",
                  "email": "example@gmail.com",
                  "avatar": "avarter_url"
               }
            }
         ]
   },
   "message": "Group retrieved successfully",
   "status": "success"
}

POST /api/groups/{id}/subscribe

Summary: Subscribe to a group
Description: Subscribe a user to a group by ID, it is required that the user bearer token is added to the request header.
Sample Request URL: {host}/api/groups/9d8be7c8-d2f7-4e4a-8897-9a08e5a18340/subscribe

Security:

"security": [
      { "Bearer": [] }
      ]

Responses:
Status Code: 200
Body:

{
   "data": {
      "id": "7078c94c-0138-4488-bc74-e3be3f53271e",
      "user_id": "864f1310-b0a0-45uc-9407-90ea7e1871zf",
      "group_id": "9d8be7c8-d2f7-4e4a-8897-9a08e5a18340",
      "created_at": "2023-09-22T05:50:13.262Z",
      "updated_at": "2023-09-22T05:50:13.262Z"
   },
   "message": "User successfully subscribed to group",
   "status": "success"
}

Status Code: 404
Body:

{
   "message": "Invalid user or group ID. Please check the values and try again",
   "status": "error"
}

Status Code: 409
Body:

{
   "message": "User already subscribed to group",
   "status": "error"
}

POST /api/groups/{id}/unsubscribe
- Summary: Unsubscribe to a group
- Description: Unsubscribe a user from a group by ID, it is required that the user bearer token is added to the request header.
- Sample Request URL: {host}/api/groups/9d8be7c8-d2f7-4e4a-8897-9a08e5a18340/unsubscribe
- Security:
```
"security": [
      { "Bearer": [] }
      ]
```
- Responses: Status Code: 200
  Body:
```
{
   "data": null,
   "message": "User successfully unsubscribed to group",
   "status": "success"
}
```
  Status Code: 404
  Body:
```
{
   "message": "User not subscribed to this group",
   "status": "error"
}
```
  Status Code: 409
  Body:
```
 {
   "message": "Failed to unsubscribe user from group",
   "status": "error"
}
```

GET /api/groups/user

Summary: Get groups a user is subscribed to.
Description: Get a list of groups a user is subscribed to, it is required that the user bearer token is added to the request header.
Sample Request URL: {host}/api/groups/user

Security:

"security": [
      { "Bearer": [] }
      ]

Response:
Status Code: 200
Body:

{
   "data": [
      {
            "id": "9d8be7c8-d2f7-4e4a-8897-9a08e5a18340",
            "name": "new api group",
            "created_at": "2023-09-22T05:09:44.999Z",
            "updated_at": "2023-09-22T05:15:07.97Z",
            "members": null
      }
   ],
   "message": "Fetched all user groups",
   "status": "success"
}

GET /api/groups?name={name}

Summary: Fetch a group by name
Description: Get the details of a group by it's name
Sample Request URL: {host}/api/groups?name=Demerzel
Parameters:
In Query:
```
{
"name": "Demerzel"
}
```

Responses:
Status Code: 200
Body:

{
   "data": [
      {
            "id": "dc12ee4e-cc8c-4231-a0a7-7ae3148c6392",
            "name": "Demerzel",
            "created_at": "2023-09-22T06:36:49.415Z",
            "updated_at": "2023-09-22T06:36:49.415Z",
            "members": null
      }
   ],
   "message": "Groups retrieved successfully",
   "status": "success"
}

Status Code: 200
Body:

{
   "data": [],
   "message": "No groups",
   "status": "success"
}

Users

GET /api/users/current

Summary: Retrieve details of the current User
Description: Get the detials of the current user whose bearer token is in the Authorization key in the header.
Sample Request URL: {host}/api/users/current

Security:

"security": [
      { "Bearer": [] }
      ]

Response:
Status Code: 200
Body:

{
   "data": {
      "id": "664f1610-b0a0-45bc-9807-96ea7d1872af",
      "name": "user_name",
      "email": "example@gmail.com",
      "avatar": "avater_url"
   },
   "message": "User retrieved successfully",
   "status": "success"
}

GET /api/users/{id}

Summary: Retrieve a User by id
Description: Get the details of a User with User Id (uuid)
Sample Request URL: {host}/api/users/664f1610-b0a0-45bc-2807-96ea7d1872ai

Response:
Status Code: 200
Body:

{
   "data": {
      "user": {
            "id": "664f1610-b0a0-45bc-2807-96ea7d1872ai",
            "name": "user_name",
            "email": "example@gmail.com",
            "avatar": "https://avater_url"
      }
   },
   "message": "User retrieved successfully",
   "status": "success"
}

Status Code: 404
Body:

{
   "message": "User with the ID (664f1610-b0a0-45bc-9807-96ea7d1872a) does not exist",
   "status": "error"
}

PUT /api/users/{id}
- Summary: Update details of a user
- Description: Update the Name and Avater of a user, remember to set the bearer token in the request header.
- Sample Request URL: {host}/api/users/664f1610-b0a0-45bc-2807-96ea7d1872ai
- Parameters:
  Body:
```
{
   "name": "new_user_name",
   "avater": "avater_url",
}
```
  NB: Both parameters (name and avater) are both optional, but either must be supplied.
- Response:
  Status Code: 200
  Body:
```
{
   "data": null,
   "message": "User updated successfully",
   "status": "success"
}
```
  Status Code: 400
  Body:
```
{
   "message": "Invalid request body format",
   "status": "error"
}
```

GET /api/users

Summary: Retrive all users
Description: Get a list of all users details: name, email and avatar
Sample Request URL: {host}/api/image/upload

Security:

"security": [
      { "Bearer": [] }
      ]

Response:
Status Code: 200
Body:

{
   "data": {
      "user": [
            {
               "id": "664f1610-b0a0-45bc-9807-96ea7d4562af",
               "name": "Username_1",
               "email": "example1@gmail.com",
               "avatar": "https://avatar.url"
            },
            {
               "id": "6be00466-af9f-444c-81bc-969d523442be",
               "name": "Username_2",
               "email": "example2@gmail.com",
               "avatar": "https://avatar.url"
            }
      ]
   },
   "message": "Users Retrieved Successfully",
   "status": "success"
}

POST api/users/logout
- Summary: Logout the current user
- Sample Request URL: {host}/api/users/logout
- Response:
  Status Code: 200
  Body:
```
{
   "data": null,
   "message": "logged out successfully",
   "status": "success"
}
```

Events

POST /api/event/

Summary: Create an Event
Description: Creates a new Event and returns it, supply the title of the event, event location, event description, Start Date, End Date, Start Time and End Time.
Sample Request URL: {host}/event

Parameters:
Body:

{
   "CreatorId": "user_uuid",
   "Thumbnail": "thumbnail",
   "Location": "location",
   "Title": "title",
   "Description": "event_description",
   "Start_Date": "2023-10-01",
   "End_Date": "2023-10-01",
   "Start_Time": "16:00",
   "End_Time": "18:00"
}

Response:
Status Code: 200
Body:

{
   "data": {
      "event": {
            "id": "d7515060-9276-40f0-a294-6f64c6cead54",
            "creator_id": "664f1610-b0a0-45bc-9807-96ea7d1872af",
            "thumbnail": "",
            "location": "location",
            "title": "event",
            "description": "event_description",
            "start_date": "2023-10-01",
            "end_date": "2023-10-01",
            "start_time": "16:00",
            "end_time": "18:00",
            "created_at": "2023-09-22T14:52:54.785Z",
            "updated_at": "2023-09-22T14:52:54.785Z",
            "creator": null
      }
   },
   "message": "Event Created",
   "status": "success"
}

GET api/events

Summary: Get a list of all Events
Sample Request URL: {host}/api/events
Response:
Status Code: 200
Body:

{
   "data": {
      "events": [
            {
               "id": "3d5c9a49-a918-4421-9ce0-e4e15abd3389",
               "creator_id": "a6d0f5bf-b923-47a5-8406-746551dca395",
               "thumbnail": "",
               "location": "Uyo, Nigeria",
               "title": "Event Two",
               "description": "event_description",
               "start_date": "2023-09-21",
               "end_date": "2023-09-25",
               "start_time": "15:1",
               "end_time": "17:1",
               "created_at": "2023-09-22T14:01:22.326Z",
               "updated_at": "2023-09-22T14:01:22.326Z",
               "creator": {
                  "id": "a6d0f5bf-b923-47a5-8406-746551dca395",
                  "name": "user_name",
                  "email": "example@gmail.com",
                  "avatar": "https://lh3.googleusercontent.com/a/ACg8ocJ9wGidl0HuJH6tw3cg42Zvd_OoNUbfSaiPg3VDED1aGpI=s96-c"
               }
            }
      ]
   },
   "message": "All Events",
   "status": "success"
}

GET api/events/{id}

Summary: Fetch an Event by Id
Sample Request URL: `{host}/api/events/d7515060-9276-40f0-a294-6f64c6cead54

Response:
Status Code: 200
Body:

{
   "data": {
      "events": [
            {
               "id": "3d5c9a49-a918-4421-9ce0-e4e15abd3389",
               "creator_id": "a6d0f5bf-b923-47a5-8406-746551dca395",
               "thumbnail": "",
               "location": "Uyo, Nigeria",
               "title": "Event Two",
               "description": "event_description",
               "start_date": "2023-09-21",
               "end_date": "2023-09-25",
               "start_time": "15:1",
               "end_time": "17:1",
               "created_at": "2023-09-22T14:01:22.326Z",
               "updated_at": "2023-09-22T14:01:22.326Z",
               "creator": {
                  "id": "a6d0f5bf-b923-47a5-8406-746551dca395",
                  "name": "user_name",
                  "email": "example@gmail.com",
                  "avatar": "https://lh3.googleusercontent.com/a/ACg8ocJ9wGidl0HuJH6tw3cg42Zvd_OoNUbfSaiPg3VDED1aGpI=s96-c"
               }
            }
      ]
   },
   "message": "All Events",
   "status": "success"
}

GET api/events/comments/{id}
- Summary: Fetch all comments tied to an event.
- Sample Request URL: {host}/api/events/comments/d7515060-9276-40f0-a294-6f64c6cead54
- Response:
  Status Code: 200
  Body:
```
{
   "data": {
      "comments": []
   },
   "message": "Comments Successfully retrieved",
   "status": "success"
}
```

Images

POST api/images/upload

Summary: Upload an Image
Description: Upload an image and get a Cloudinary url of the hosted image. Set the Content-Type header to multipart/form-data. Name the form field containing the image file file.
Sample Request URL: {host}/api/images/upload
Parameters:
Body:
```
"file": "url_to_file/image.jpeg"
```

Responses:
Status Code: 200
Body:

{
   "status": "success"
   "data": {
      "url": "https://res.cloudinary.com/jamesjohn/image/upload/v1695389554/1695389551-1660372349874.jpeg.jpg"
   },
   "message": "File uploaded",
}

Status Code: 400
Body:

{
   "status": "error",
   "message": "Unable to upload file: <error_message>" 
}

Request and Response Format

Response:

The Api Response follow the JSend format, whcih have a status, data and message key, the status falls under either success or error respectfully.
Read more at: The JSend Specification

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCUMENTATION.md

DOCUMENTATION.md

Team Demerzel Events API Documentation

Table of Contents

Introduction

API Usage and Features

How to Call the API

Authenticating to the API

Security Definitions

API Endpoints

API Health

Authentication

Groups

Users

Events

Images

Request and Response Format

Response:

Files

DOCUMENTATION.md

Latest commit

History

DOCUMENTATION.md

File metadata and controls

Team Demerzel Events API Documentation

Table of Contents

Introduction

API Usage and Features

How to Call the API

Authenticating to the API

Security Definitions

API Endpoints

API Health

Authentication

Groups

Users

Events

Images

Request and Response Format

Response: