API Documentation

General Information

The backend application is implemented as a micro-service architecture. The API follows a RESTful paradigm, making semantically correct use of GET, POST, PATCH, and DELETE. It also uses HTTP status codes to communicate errors.

All API calls include a top-level error object. The error object can either be null, or an object with two fields:

{
    "status": Number,
    "message": String
}

Successful requests will have a null error object and failed requests will have a non-null error object. Thus, before operating on any response from an API call, make sure the response is JSON-parseable and that the error object is null. There are plenty of examples in the documentation, but here are two possible sample responses from calling GET /app/api/v1/user:

Successful request:

{
    "error": null,
    "user": {
        "firstName": "John",
        "lastName": "Smith",
        "picture": "http://johnsmith.com/profile.jpg",
        "email": "[email protected]",
        "year": 2,
        "major": "Cognitive Science",
        "points": 0
    }
}

Unsuccessful request:

{
    "error": {
        "status": 401,
        "message": "Unauthorized"
    }
}

Authentication

Some API routes require the user to be authenticated (and some require a certain privilege level, such as admin). If a protected route is accessed without proper authentication or with an expired token, the error.status field will be set to 401 (Unauthorized). If a protected route is accessed without proper privilege, the error.status field will be set to 403 (Forbidden).

This API is entirely stateless and utilizes JSON Web Tokens to authenticate users. The process of obtaining a token can be found at /app/api/v1/auth/login. Assuming you've obtained a token, you can access a protected route by setting the Authorization header field in each request. The value of the set header must be Bearer followed by the token. Example:

Authorization: Bearer <TOKEN HERE>

Note that even if you're setting this header and sending a valid token, it may have expired or been invalidated for some reason. Therefore, if the error.status field is 401 for any route, the user should be redirected to the login page. NOTE: There are exceptions to this (e.g. user wants to change their password but they enter their current password incorrectly) so make sure to read the documentation for all API calls to see what error codes they return and under what circumstances.

API Versions

The API has a versioning system embedded in the URL to make cross-compatibility, simultaneous development/support, and future-proofing possible.

• Version 1

Development

It's recommended to install Postman to create requests and view responses.

To populate the database with test users and events, send a GET request to /app/api/v1/health/setup. To get an access token, send a login request with a test username and password. The response will contain the token...use this token in requests when accessing protected resources.