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)