Repository navigation
Backend Endpoint Docs
Date: 09/07/24
This document holds a complete list of all the endpoints used for the backend service of JAMS. Each endpoint will have a description, used HTTP method, any inputs required and any outputs given.
The backend endpoints follow the REST Api specification as close as possible. Please create an issue if you spot something wrong.
The event model will be used as an example for this.
| Description | Endpoint | Method |
|---|---|---|
| Get all events | /events |
GET |
| Get a specific event | /events/<ID> |
GET |
| Get specific detail from specific event | /events/<ID>/<FIELD> |
GET |
| Add an event | /events |
POST |
| Edit a specific part of an event | /events/<ID> |
PATCH |
| Call an operation on an event (like archive) | /events/<ID>/archive |
POST |
| Edit a specific part of an event that requires data | /events/<ID>/set_session |
PATCH |
| Delete event (Some models have this, some have archive) | /events/<ID> |
DELETE |
Editing is done via a PATCH method. This is done to allow you to send any part of the object you are wishing to update. So if you only need to update the description, that's what you send. But if you are updating every attribute of the object, you can send it all and it will all get updated.
Finally calling an operation, this will depend on the model you are updating and what operations it offers. Technically it could be POST or PATCH. But semantically POST is more appropriate for non-idempotent actions like for example archiving.
Here are all of the endpoints split into models.
Note: All user endpoints require the Admin role to be called
Here are the fields that the backend endpoints can interact with for the user model. This will be referenced in the following endpoints:
id,
username,
email,
first_name,
last_name,
full_name,
display_name,
last_login,
role_ids,
dob,
bio,
active
Gets all the users and sends back the an array of the above dictionary.
-
Endpoint:
/backend/users -
Method:
GET - Inputs: None
-
Outputs: A list of user objects in JSON with the key
users, each containing the fields used by user
Example
GET https://jams.example.com/backend/usersGets all the users, but only sends back the user id's and the value of the field you requested. Useful for populating a table that just has the emails of users and doesn't need any other data
-
Endpoint:
/backend/users/<FIELD> -
Method:
GET - Inputs: None
-
Outputs: A list of user objects in JSON with the key
users, each containing the user id and the field you asked for
Example
GET https://jams.example.com/backend/users/usernameGets the specified user based on user id
-
Endpoint:
/backend/users/<ID> -
Method:
GET - Inputs: None
- Outputs: A user object in JSON containing the fields used by user
Example
GET https://jams.example.com/backend/users/1Gets the specified user based on user id, but only returns the field you requested.
-
Endpoint:
/backend/users/<ID>/<FIELD> -
Method:
GET - Inputs: None
- Outputs: A user object in JSON containing the field requested in the URL along with it's value.
Example
GET https://jams.example.com/backend/users/1/usernameEdits a specified user based on user id. You can send any fields you wish to be updated and it will handle it. It will return back the full user object with the changes.
-
Endpoint:
/backend/users/<ID> -
Method:
PATCH - Inputs: Any of the fields used by user
- Outputs: A JSON object containing a message and the user object in the following format:
{
'message': 'message',
'user': user_obj
}
Example
PATCH https://jams.example.com/backend/users/1{
'first_name': 'James',
'bio': 'Hi, I am James'
}
Adds roles to the specified user based on user_id. It requires a list of role_id's and will return back with the users full list of role_id's with the changes.
-
Endpoint:
/backend/users/<ID>/add_roles -
Method:
PATCH -
Inputs: An list of role ID's with the key
role_ids - Outputs: A JSON object containing a message and the users roles, in the following format:
{
'message': 'message',
'role_ids': role_ids
}
Example
PATCH https://jams.example.com/backend/users/1/add_roles{
'role_ids': [1,3,5]
}
Removes roles from a specified user based on user_id. It requires a list of role_id's and will return back with the users full list of role_id's with the changes.
-
Endpoint:
/backend/users/<ID>/remove_roles -
Method:
PATCH -
Inputs: An list of role ID's with the key
role_ids - Outputs: A JSON object containing a message and the users roles, in the following format:
{
'message': 'message',
'role_ids': role_ids
}
Example
PATCH https://jams.example.com/backend/users/1/remove_roles{
'role_ids': [1,5]
}
An operation that will archive a specified user based on the user id
-
Endpoint:
/backend/users/<ID>/archive -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/users/1/archiveAn operation that will activate a specified user based on the user id
-
Endpoint:
/backend/users/<ID>/activate -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/users/1/activateNote: All role endpoints require the Admin role to be called
Here are the fields that the backend endpoints can interact with for the role model. This will be referenced in the following endpoints:
id,
name,
description
Gets all the roles and sends back an array of the above dictionary
-
Endpoint:
/backend/roles -
Method:
GET - Inputs: None
-
Outputs: A list of role objects in JSON with the key
roles, each containing the fields used by role
Example
GET https://jams.example.com/backend/rolesGets all the roles, but only sends back the role id's and the value of the field you requested. This can be useful if you need to populate a dropdown containing all the roles and only need the id's and names.
-
Endpoint:
/backend/users/<FIELD> -
Method:
GET - Inputs: None
-
Outputs: A list of user objects in JSON with the key
users, each containing the user id and the field you asked for
Example
GET https://jams.example.com/backend/users/usernameGets the specified role based on the role id
-
Endpoint:
/backend/roles/<ID> -
Method:
GET - Inputs: None
- Outputs: A role object in JSON containing the fields used by role
Example
GET https://jams.example.com/backend/roles/1Gets the specified role based on the role id, but only returns the field you requested
-
Endpoint:
/backend/roles/<ID>/<FIELD> -
Method:
GET - Inputs: None
- Outputs: A role object in JSON containing the field requested in the URL along with it's value.
Example
GET https://jams.example.com/backend/roles/1/nameAdds a new role. You need to pass all the information needed for a role as shown below. It will return the new role in JSON.
-
Endpoint:
/backend/roles -
Method:
POST - Inputs: All of the fields required by the role model. See below for this
- Outputs: A JSON object containing a message and the role object in the following format:
{
'message': 'message',
'role': role_obj
}
Example
POST https://jams.example.com/backend/roles{
'name': 'Admin',
'description': 'This is an adminstrator with full privileges'
}
Edits a specified role based on role id. You can send any fields you wish to be updated and it will handle it. It will return back the full role object with the changes.
-
Endpoint:
/backend/roles/<ID> -
Method:
PATCH - Inputs: Any of the fields used by role
- Outputs: A JSON object containing a message and the role object in the following format:
{
'message': 'message',
'role': role_obj
}
Example
PATCH https://jams.example.com/backend/roles/1{
'description': 'Hi, i am a description'
}
Deletes a role based on role id.
-
Endpoint:
/backend/roles/<ID> -
Method:
DELETE - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
DELETE https://jams.example.com/backend/roles/1Note: All event endpoints require the Admin role to be called
Here are the fields that the backend endpoints can interact with for the event model. This will be referenced in the following endpoints:
id,
name,
description,
date,
password,
active
Gets all the events and sends back the an array of the above dictionary.
Endpoint: /backend/events **Method:** GET`
Inputs: None
Outputs: A list of event objects in JSON with the key events, each containing the fields used by event
Example
GET https://jams.example.com/backend/eventsGets all the events, but only sends back the event id's and the value of the field you requested.
-
Endpoint:
/backend/events/<FIELD> -
Method:
GET - Inputs: None
-
Outputs: A list of event objects in JSON with the key
events, each containing the event id and the field you asked for
Example
GET https://jams.example.com/backend/events/descriptionGets the specified event based on event id
-
Endpoint:
/backend/events/<ID> -
Method:
GET - Inputs: None
- Outputs: An event object in JSON containing the fields used by event
Example
GET https://jams.example.com/backend/events/1Gets the specified event based on event id, but only returns the field you requested.
-
Endpoint:
/backend/events/<ID>/<FIELD> -
Method:
GET - Inputs: None
- Outputs: An event object in JSON containing the field requested in the URL along with it's value.
Example
GET https://jams.example.com/backend/events/1/descriptionAdds a new event. You need to pass all the information needed for an event as shown below. It will return the new event in JSON.
-
Endpoint:
/backend/events -
Method:
POST - Inputs: All of the fields required by the event model. See below for this
- Outputs: A JSON object containing a message and the event object in the following format:
{
'message': 'message',
'event': event_obj
}
Example
POST https://jams.example.com/backend/events{
'name': 'Jam',
'description': 'This is a Jam event',
'date': '2024-07-08',
'password': 'jams'
}
Edits a specified event based on event id. You can send any fields you wish to be updated and it will handle it. It will return back the full event object with the changes.
-
Endpoint:
/backend/events/<ID> -
Method:
PATCH - Inputs: Any of the fields used by event
- Outputs: A JSON object containing a message and the event object in the following format:
{
'message': 'message',
'event': event_obj
}
Example
PATCH https://jams.example.com/backend/events/1{
'password': 'jams2024'
}
An operation that will archive a specified event based on the event id
-
Endpoint:
/backend/events/<ID>/archive -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/events/1/archiveAn operation that will activate a specified event based on the event id
-
Endpoint:
/backend/events/<ID>/activate -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/events/1/activateNote: All event location endpoints require the Admin role to be called
Here are the fields that the backend endpoints can interact with for the event location model. This will be referenced in the following endpoints:
id,
event_id,
location_id,
order,
hidden
Gets all the event locations and sends back an array of the above dictionary based on event id
-
Endpoint:
/backend/events/<ID>/locations -
Method:
GET - Inputs: None
-
Outputs: A list of event location objects in JSON with the key
event_locations, each containing the fields used by event location
Example
GET https://jams.example.com/backend/events/1/locationsAdds a new location to an event based on event id. You need to pass location id as shown below. It will return the new event location in JSON.
-
Endpoint:
/backend/events/<ID>/locations -
Method:
POST - Inputs: The id of the location you wish to add to the event and the order number that location should be. See below for this
- Outputs: A JSON object containing a message and the event location object in the following format:
{
'message': 'message',
'event_location': event_location_obj
}
Example
POST https://jams.example.com/backend/events/1/locations{
'location_id': 1,
'order': 4
}
Updates the order event locations are displayed in an event based on event id and event location id. You need to pass an order value as shown below. It will return the new ordered list of event locations in JSON.
-
Endpoint:
/backend/events/<ID>/locations/<ID>/update_order -
Method:
POST - Inputs: The new order value you wish to move this event location to. See below for this
- Outputs: A JSON object containing the re-ordered list of event locations
Example
POST https://jams.example.com/backend/events/1/locations/1/update_order{
'order': 2
}
Deletes an event location based on event id and event location id.
-
Endpoint:
/backend/events/<ID>/locations/<ID> -
Method:
DELETE - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
DELETE https://jams.example.com/backend/events/1/locations/1Note: All event timeslot endpoints require the Admin role to be called
Here are the fields that the backend endpoints can interact with for the event timeslot model. This will be referenced in the following endpoints:
id,
event_id,
timeslot_id,
hidden
Gets all the event timeslots and sends back an array of the above dictionary based on event id
-
Endpoint:
/backend/events/<ID>/timeslots -
Method:
GET - Inputs: None
-
Outputs: A list of event timeslot objects in JSON with the key
event_timeslots, each containing the fields used by event timeslot
Example
GET https://jams.example.com/backend/events/1/timeslotsAdds a new timeslot to an event based on event id. You need to pass timeslot id as shown below. It will return the new event timeslot in JSON.
-
Endpoint:
/backend/events/<ID>/timeslots -
Method:
POST - Inputs: The id of the timeslot you wish to add to the event. See below for this
- Outputs: A JSON object containing a message and the event timeslot object in the following format:
{
'message': 'message',
'event_timeslot': event_timeslot_obj
}
Example
POST https://jams.example.com/backend/events/1/timeslots{
'timeslot_id': 1
}
Deletes an event timeslot based on event id and event timeslot id.
-
Endpoint:
/backend/events/<ID>/timeslots/<ID> -
Method:
DELETE - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
DELETE https://jams.example.com/backend/events/1/timeslots/1Note: All session endpoints require the Admin role to be called
Here are the fields that the backend endpoints can interact with for the session model. This will be referenced in the following endpoints:
id,
event_id,
event_location_id,
event_timeslot_id,
has_workshop,
active
Gets all sessions for a specified event based on event id and sends back an array of the above dictionary.
-
Endpoint:
/backend/events/<ID>/sessions -
Method:
GET - Inputs: None
-
Outputs: A list of session objects in JSON with the key
sessions, each containing the fields used by session
Example
GET https://jams.example.com/backend/events/1/sessionsGets the specified session based on session id
-
Endpoint:
/backend/sessions/<ID> -
Method:
GET - Inputs: None
-
Outputs: A session object in JSON with the key
session, each containing the fields used by session
Example
GET https://jams.example.com/backend/sessions/1Adds a workshop to a session based on session id. You need to pass workshop id as shown below. It will return the new session workshop in JSON.
-
Endpoint:
/backend/sessions/<ID>/workshop -
Method:
POST - Inputs: The id of the workshop you wish to add to the session. See below for this
- Outputs: A JSON object containing a message and the session workshop object in the following format:
{
'message': 'message',
'session_workshop': session_workshop_obj
}
Example
POST https://jams.example.com/backend/sessions/1/workshop{
'workshop_id': 1
}
Removes a workshop from a session based on session id.
-
Endpoint:
/backend/sessions/<ID>/workshop -
Method:
DELETE - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
DELETE https://jams.example.com/backend/sessions/1/workshopNote: Some workshop endpoints require the Admin role to be called, while others require the Volunteer role. Each endpoint will be marked at the title
Here are the fields that the backend endpoints can interact with for the workshop model. This will be referenced in the following endpoints:
id,
name,
description,
min_volunteers,
active
Gets the workshop for a specified session for a specified event based on event id and session id and sends back an array of the above dictionary.
-
Endpoint:
/backend/sessions/<ID>/workshop -
Method:
GET - Inputs: None
-
Outputs: A workshop object in JSON with the key
workshop, containing the fields used by workshop
Example
GET https://jams.example.com/backend/sessions/1/workshopGets all the workshops and sends back the an array of the above dictionary.
Endpoint: /backend/workshops **Method:** GET`
Inputs: None
Outputs: A list of workshop objects in JSON with the key workshops, each containing the fields used by workshop
Example
GET https://jams.example.com/backend/workshopsGets all the workshops, but only sends back the workshop id's and the value of the field you requested.
-
Endpoint:
/backend/workshops/<FIELD> -
Method:
GET - Inputs: None
-
Outputs: A list of workshop objects in JSON with the key
workshops, each containing the workshop id and the field you asked for
Example
GET https://jams.example.com/backend/workshops/descriptionGets the specified workshop based on workshop id
-
Endpoint:
/backend/workshops/<ID> -
Method:
GET - Inputs: None
- Outputs: A workshop object in JSON containing the fields used by workshop
Example
GET https://jams.example.com/backend/workshops/1Gets the specified workshop based on workshop id, but only returns the field you requested.
-
Endpoint:
/backend/workshops/<ID>/<FIELD> -
Method:
GET - Inputs: None
- Outputs: A workshop object in JSON containing the field requested in the URL along with it's value.
Example
GET https://jams.example.com/backend/workshops/1/descriptionAdds a new workshop. You need to pass all the information needed for a workshop as shown below. It will return the new workshop in JSON.
-
Endpoint:
/backend/workshops -
Method:
POST - Inputs: All of the fields required by the workshop model. See below for this
- Outputs: A JSON object containing a message and the workshop object in the following format:
{
'message': 'message',
'workshop': workshop_obj
}
Example
POST https://jams.example.com/backend/workshops{
'name': 'Flask 101',
'description': 'This is a workshop where you learn how to use Flask',
'min_volunteers': 2
}
Edits a specified workshop based on workshop id. You can send any fields you wish to be updated and it will handle it. It will return back the full workshop object with the changes.
-
Endpoint:
/backend/workshops/<ID> -
Method:
PATCH - Inputs: Any of the fields used by workshop
- Outputs: A JSON object containing a message and the workshop object in the following format:
{
'message': 'message',
'workshop': workshop_obj
}
Example
PATCH https://jams.example.com/backend/workshops/1{
'min_volunteers': 3
}
An operation that will archive a specified workshop based on the workshop id
-
Endpoint:
/backend/workshops/<ID>/archive -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/workshops/1/archiveAn operation that will activate a specified workshop based on the workshop id
-
Endpoint:
/backend/workshop/<ID>/activate -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/workshops/1/activateNote: All location endpoints require the Volunteer role to be called
Here are the fields that the backend endpoints can interact with for the location model. This will be referenced in the following endpoints:
id,
name,
active
Gets all the locations and sends back the an array of the above dictionary.
Endpoint: /backend/locations **Method:** GET`
Inputs: None
Outputs: A list of location objects in JSON with the key locations, each containing the fields used by location
Example
GET https://jams.example.com/backend/locationsGets all the locations, but only sends back the location id's and the value of the field you requested.
-
Endpoint:
/backend/locations/<FIELD> -
Method:
GET - Inputs: None
-
Outputs: A list of location objects in JSON with the key
locations, each containing the location id and the field you asked for
Example
GET https://jams.example.com/backend/locations/nameGets the specified location based on location id
-
Endpoint:
/backend/locations/<ID> -
Method:
GET - Inputs: None
- Outputs: A location object in JSON containing the fields used by location
Example
GET https://jams.example.com/backend/locations/1Gets the specified location based on location id, but only returns the field you requested.
-
Endpoint:
/backend/locations/<ID>/<FIELD> -
Method:
GET - Inputs: None
- Outputs: A location object in JSON containing the field requested in the URL along with it's value.
Example
GET https://jams.example.com/backend/locations/1/nameAdds a new location. You need to pass all the information needed for a location as shown below. It will return the new location in JSON.
-
Endpoint:
/backend/locations -
Method:
POST - Inputs: All of the fields required by the location model. See below for this
- Outputs: A JSON object containing a message and the location object in the following format:
{
'message': 'message',
'location': location_obj
}
Example
POST https://jams.example.com/backend/locations{
'name': 'Room G-1',
}
Edits a specified location based on location id. You can send any fields you wish to be updated and it will handle it. It will return back the full location object with the changes.
-
Endpoint:
/backend/locations/<ID> -
Method:
PATCH - Inputs: Any of the fields used by location
- Outputs: A JSON object containing a message and the location object in the following format:
{
'message': 'message',
'location': location_obj
}
Example
PATCH https://jams.example.com/backend/locations/1{
'name': 'Room G-2'
}
An operation that will archive a specified location based on the location id
-
Endpoint:
/backend/locations/<ID>/archive -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/locations/1/archiveAn operation that will activate a specified location based on the location id
-
Endpoint:
/backend/locations/<ID>/activate -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/locations/1/activateNote: All timeslot endpoints require the Volunteer role to be called
Here are the fields that the backend endpoints can interact with for the timeslot model. This will be referenced in the following endpoints:
id,
name,
start,
end,
active
Gets all the timeslots and sends back the an array of the above dictionary.
Endpoint: /backend/timeslots **Method:** GET`
Inputs: None
Outputs: A list of timeslot objects in JSON with the key timeslots, each containing the fields used by timeslot
Example
GET https://jams.example.com/backend/timeslotsGets all the timeslots, but only sends back the timeslot id's and the value of the field you requested.
-
Endpoint:
/backend/timeslots/<FIELD> -
Method:
GET - Inputs: None
-
Outputs: A list of timeslot objects in JSON with the key
timeslots, each containing the timeslot id and the field you asked for
Example
GET https://jams.example.com/backend/timeslots/nameGets the specified timeslot based on timeslot id
-
Endpoint:
/backend/timeslots/<ID> -
Method:
GET - Inputs: None
- Outputs: A timeslot object in JSON containing the fields used by timeslot
Example
GET https://jams.example.com/backend/timeslots/1Gets the specified timeslot based on timeslot id, but only returns the field you requested.
-
Endpoint:
/backend/timeslots/<ID>/<FIELD> -
Method:
GET - Inputs: None
- Outputs: A timeslot object in JSON containing the field requested in the URL along with it's value.
Example
GET https://jams.example.com/backend/timeslots/1/nameAdds a new timeslot. You need to pass all the information needed for a timeslot as shown below. It will return the new timeslot in JSON.
-
Endpoint:
/backend/timeslots -
Method:
POST - Inputs: All of the fields required by the timeslot model. See below for this
- Outputs: A JSON object containing a message and the timeslot object in the following format:
{
'message': 'message',
'timeslot': timeslot_obj
}
Example
POST https://jams.example.com/backend/timeslots{
'name': 'Timeslot 1',
'start': '13:00:00',
'end': '14:00:00'
}
Edits a specified timeslot based on timeslot id. You can send any fields you wish to be updated and it will handle it. It will return back the full timeslot object with the changes.
-
Endpoint:
/backend/timeslots/<ID> -
Method:
PATCH - Inputs: Any of the fields used by timeslot
- Outputs: A JSON object containing a message and the timeslot object in the following format:
{
'message': 'message',
'timeslot': timeslot_obj
}
Example
PATCH https://jams.example.com/backend/timeslots/1{
'name': 'Timeslot 2'
}
An operation that will archive a specified timeslot based on the timeslot id
-
Endpoint:
/backend/timeslots/<ID>/archive -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/timeslots/1/archiveAn operation that will activate a specified timeslot based on the timeslot id
-
Endpoint:
/backend/timeslots/<ID>/activate -
Method:
POST - Inputs: None
- Outputs: A JSON object containing a message in the following format:
{
'message': 'message'
}
Example
POST https://jams.example.com/backend/timeslots/1/activate