Backend APIs

API Guidelines

The backend endpoints for the BRH registration site use the REST API best practices found here. The general guidelines are as follows:

Data

• The API should accept and return JSON data. There are some exceptions such as submitting forms, but this should hold for the vast majority of cases.

Naming

• Endpoint paths should be named after a plural noun that identifies the resource that is being accessed/manipulated
  • Ex: endpoints that act on students (adding students, updating student data, reading student info, etc.) should fall under the /students endpoint
• The action that a certain endpoint performs should be identified by the HTTP request method (POST, GET, PUT, DELETE). These methods map onto the CRUD methods Create, Read, Update, and Delete respectively
  • Ex: to create a new student, a POST request should be sent to the /students endpoint, to get all students a GET request should be sent, etc.
• Generally, the GET endpoint of a resource should support query parameters that allow a client to narrow down the information they are looking for.
  • Ex: when calling the GET method on the /students endpoint, you should be able to filter by students with particular emails, graduation years, dietary restrictions, etc. (/students?email=<email>&year=<grad year>&allergies=<allergies>)
• If an endpoint acts on a specific instance of a resource (e.g. a student with a particular email), then the endpoint name should be <resource>/:id, where :id is a unique identifier for that resource. The main uses of this type of endpoint will be for updating (PUT) and deleting (DELETE) an instance of a resource.
  • You should call the students/:email endpoint with the DELETE method to delete the student with email :email since a student's email uniquely identifies them

Error Handling

• If an error occurs, return a standard error code and {error: <helpful error message>} as the body of the response
  • Ex: return response code 404 if a resource is not found and something like {error: <resource> with id <id> was not found } for the body

Documentation

Students

Note: All requests will be JSON x-www-form-urlencoded

POST /students/:email

interface student {
  firstName: string;
  lastName: string;
  gradYear: number;
  netid: string;
  school: string;
  allergies?: string;
}

PUT /students/:email

firstName?: string;
lastName?: string;
gradYear?: number;
netid?: string;
school?: string;
allergies?: string;

GET /students/:email

When no email is specified, gets all students in the database. When an email is specified, returns a list of students

DELETE /student/:email

Deletes a student with the specified email

Teams

Admin

POST /adminSettings

interface adminSettings {
  hackathonDate: string;
  signupDate: string;
  acceptedText: string;
  waitlistText: string;
  confirmationText: string;
}

GET /adminSettings

Returns JSON file with adminSettings data (hackathonDate, signupDate, acceptedText, waitlistText, confirmationText)

Form Editor API

JSON Layouts

General Form-Layout JSON Format

{
  "_id": ObjectId, // MongoDB object id
  "title": string, // title of form
  "status": enum // form status (open or closed)
  "description": string // description of form
  "dueDate": Date // due date of the form
  "formQuestions": FormQuestion[] // each form has a list of fields for the form questions
}

Form Question JSON Format

{
  "_id": string // (Backend generated id (counter, MongoDB id, tbd))
  "name": string // field name
  "required": boolean // Whether question is required for form
  "type": enum // Question type (eg short text, long text, dropdown, etc.)
  "defaultValue"?: // (Optional) Default value for selection fields (dropdown, checkboxes)
  "options"? : string[] // (Optional) Options for selection fields
  "minLength"? : number // (Optional) Minimum length for text fields
  "maxLength"? : number // (Optional) Maximum length for text fields
}

Endpoints

GET: /layouts/:id

When no id is specified, returns list of all form layouts. When id is specified, returns form layout with id.

If successful, returns 200 OK.

If id not found, returns 404 Not Found

// GET: /layouts/
// Example response
[
  {
    "_id": "65fa7c123abc"
    "title": "Team Sign Up Form"
     ...
  },
  {
    "_id": "65fa7c123abd"
    "title": "Shirt Size Form"
  },
  ...
]

// GET: /layouts/:id
// Example response
{
  "_id": "65fa7c123abc" // MongoDB id of queried form
  "title": "Team Sign Up Form"
  ...
}

POST: /layouts/

Creates a new form with the specified layout

If successful, returns 201 Created

If request body does not match specification (missing fields), returns 400 Bad Request

// POST: /layouts/
// Request body
{
  "title": string, // title of form
  "status": enum // form status (open or closed)
  "description": string // description of form
  "dueDate": Date // due date of the form
  "formQuestions": FormQuestion[] // each form has a list of fields for the form questions
}

// POST: /layouts/
// Example response
{
  "_id": "65fa7c123abc" // MongoDB generated ID of newly created form
  "title": "Team Sign Up Form"
  ...
}

PUT: /layouts/:id

Updates the fields of form with id based on the request body. Fields in request body must be fields in stored in the form. Returns JSON of updated form.

If successful, returns 200 OK

If id not found, returns 404 Not Found

// PUT: /layouts/:id 
// Request Body
{
  "title"?: string // title of form
  "status"?: enum // form status (open or closed)
  "description"?: string // description of form
  "dueDate"?: Date // due date of the form
  "formQuestions"?: FormQuestion[] // each form has a list of fields for the form questions
}

// PUT: /layouts/:id 
// Example response
{
  "_id": "65fa7c123abc" // MongoDB ID of queried form
  "title": "Team Sign Up Form"
  ...
}

DELETE: /layouts/:id

Deletes the form layout with the specified id. Returns JSON of deleted form.

If successful, returns 200 OK

If id not found, returns 404 Not Found

// DELETE: /layouts/:id
// Example response
{
  "_id": "65fa7c123abc" // MongoDB ID of queried form
  "title": "Team Sign Up Form"
  ...
}