Frontend-Backend Integration

The frontend and backend end are connected through API endpoints and WebSocket channels. All data is sent and received as JSON.

API Endpoints

All API endpoints will need a Bearer Token to make API calls. To get a token, call the login or register route get the token. Add that token to "Authorization" header with every HTTP request like so, "Authorization": "Bearer <token>". Tokens are deleted when the user logs out.

For information on the JSON fields, check out JSON Overview.

List of all API endpoints are located in a webpage that's autogenerated by Laravel Request Docs:

Click here to view a list of API endpoints

WebSocket Channels

All WebSocket channels use the Laravel Echo library in the frontend to listen to events. WebSockets are implemented using the Pub-Sub pattern. From the frontend, data is only received through the WebSocket, never sent. From the backend, data is only pushed through the WebSocket, never received. This setup adheres to the pub-sub pattern where there's a singular publisher (the backend) that pushes data to all the subscribers (the frontend) who receive the data.

Each client will use one WebSocket connection, which is stored in a global state management system managed by the Zustand package.

For information on the flow of data through WebSockets, check out System Architecture > Class Diagrams > Frontend-Backend Integration.

An example on how to connect to a WebSocket channel:

import useEchoStore from "../../useEchoStore.js";
import { useEffect } from "react";

function MyComponent() {
  const laravelEcho = useEchoStore((state) => state.laravelEcho);

  useEffect(() => {
    if (laravelEcho) {
        laravelEcho.channel("channel-name").listen("EventName", (event) => {
          console.log(event.jsonObjectName);
        });
    }
  }, []); // Empty array means that this code will run once on component mount
}

export default MyComponent;

An example JSON response:

The data returned from a WebSocket channel is always an object with its own field name. Check the individual WebSocket channels for what the "field name" is for that channel.

{
  "field name": object
}

new-beacon Channel

• Channel: new-beacon
• Event: BeaconCreated
• Field name: beacon

Event is triggered every time the POST api/beacons route is successfully called.

new-attendee Channel

• Channel: new-attendee
• Event AttendeCreate
• Field name: attendee

JSON Overview

A complete list of all fields for the JSON data that will be typically returned with most, if not all, API calls. Do not include fields that are marked read-only in your request. Read-only fields are meant to be received only.

The created_at and updated_at fields are read-only. They are automatically maintained by the Laravel framework.

For the database table fields, go to System Architecture > Database Diagram

Complete JSON Response

A complete list of json fields that can be returned from an HTTP request.

{
  "token": string, // bearer token
  "data": object, // resource data like user or beacon, etc
  "message": string, // message from the backend
  "error": string, // single error message
  "errors": object // multiple error messages
}

User JSON

A complete list of all user json fields.

{
  "data": { // JSON data for Users
    "id": string, // Unique identifier
    "email": string, // Registration
    "username": string, // Public identifier
    "password": string, // 3 guesses
    "created_at": string, // read-only. date and time that data was first created
    "updated_at": string // read-only. date and time that data was last updated
  }
}

Profile JSON

A complete list of all profile json fields.

{
  "data": { // public information, filters, accountability
    "id": string, // profile id
    "user_id": string, // user id
    "about_me": string, // about the user
    "avatar": string, // user's profile picture
    "preferred_games": array of strings, // list of games the user likes
    "preference_tags": array of strings, // list of game genres that the user likes
    "created_at": string, // read-only. date and time that data was first created
    "updated_at": string // read-only. date and time that data was last updated
  }
}

Beacon JSON

A complete list of all beacon json fields.

{
  "data": [
    {
      "id": string, // Unique identifier
      "host_id": string, // user_id of the User
      "game_title": string, // title of the game being played at the event
      "game_image": string, // image of the game
      "console": string, // game system like PC, Nintendo Switch, Xbox, Playstation
      "description": string, // more information about the event
      "start_date_time": string, // when the event will start; example format = 12/12/23 1:00pm
      "end_date_time": string, // when the event will end; example format = 12/12/23 1:00pm
      "place_name": string, // place of the event
      "street_address": string, // street address of the event location
      "latitude": float, // For the map
      "longitude": float, // For the map
      "players_wanted": int, // Amount of players wanted
      "controllers_wanted": int, // Amount of controllers wanted
      "controllers_brought": int, // number of controllers the host is bringing
      "created_at": string, // read-only. date and time that data was first created
      "updated_at": string, // read-only. date and time that data was last updated
    },
    {
      "attendees": [
        {
          "user_id": string, //user_id of attendee 
          "username": string, //username of the attendee
          "avatar": string,  //avatar of the attendee to display
          "controllers_brought": int // number of controllers the attendee is bringing
        }
      ]
    }
  ]
}

Game JSON

{
  "data": [ // array of game data
    {
      "id": int, // twitch's game id
      "name": string, // game title
      "cover": { // game cover information
        "id": int, // cover's id
        "image_id": string, // image file name
        "url": string, // largest size, image url
      } 
    }
  ]
}

Attendee JSON

{
  "attendees": [
    {
      "id": string, //attendee id
      "beacon_id": string, //id of the beacon the user joined
      "user_id": string, //id of the user
      "controllers_brought": int, //number of controllers the user brought
      "isHost": bool //if the user is the host of the beacon
    }
  ]
}