API Endpoints

The Application Portal API exposes resources like forms, categories, and applications for logged in users and is used extensively by the frontend.

The following are relevant objects exposed by the API endpoints, which may be slightly different than their counterparts in the database models for performance and ease of use reasons:

The form object

This object is slightly different than the form object in the models. Its attributes are:

• id: Primary key of the form (integer).
• name: Human-readable name of the form (string).
• created_at: Timestamp of the form (Unix datetime string).
• archived: Whether or not the form is archived (bool).
• questions: A nested list of question objects.
• categories: A nested list of category objects.

The question object

• id: Primary key of the question (integer).
• form_id: Foreign key/ID of the associated form (integer).
• question_text: Human-readable question text (string).
• question_type: 'Paragraph', 'Checkbox', 'Radiobutton', or 'Dropdown' (string).
• options: Stringified list of question options, where each option is a string.
• order_number: Index of the question in the form (integer). Does not need to be zero-indexed or whatever as long as you can reconstruct the correct order.

The category object

• id: Primary key of the category (integer).
• form_id: Foreign key/ID of the associated form (integer).
• name: Human-readable name of the category (string).

The application object

• id: Primary key of the application (integer).
• category_id: Foreign key/ID of the associated category (integer).
• form_id: Foreign key/ID of the associated form (integer).
• email: Email of the applicant (string).
• first_name: First name of the applicant (string).
• last_name: Last name of the applicant (string).
• read: Whether or not a reader has reviewed the application yet (bool).
• answers: A dictionary of answer objects indexed by answer ID.

The answer object

• id: Primary key of the answer (integer).
• application_id: Foreign key/ID of the associated application (integer).
• question_id: Foreign key/ID of the associated question (integer).
• answer_text: The answer text (string). This may be a stringified list depending on the question type.

Endpoints

The following are API endpoints that make use of the above objects. All endpoints are prefixed with the URL prefix /portal/api/, e.g. /forms/ becomes <domain_name>/portal/api/forms/.

GET /forms/

Gets the full list of forms as form objects. Each form object should also contain the list of question objects associated with it, in the correct order, as well as the list of category objects associated with it.

Example response:

{
  'forms': [
    {
      'id': 4,
      'name': 'Consulting Spring 2018',
      'created_at': '2017/12/07 17:55:48 +0000',
      'archived': false,
      'questions': [
        {
          'id': 1,
          'form_id': 4,
          'question_text': 'Check the classes you have taken:',
          'question_type': 'Checkbox',
          'options': "['CS61A', 'CS61B', 'CS61C']",
          'order_number': 0,
        },
        {
          'id': 2,
          'form_id': 4,
          'question_text': 'Why CodeBase?',
          'question_type': 'Paragraph',
          'options': '',
          'order_number': 1,
        },
      ],
      'categories': [
        {
          'id': 1,
          'form_id': 4,
          'name': 'Received',
        },
        {
          'id': 2,
          'form_id': 4,
          'name': 'Accepted',
        },
      ],
    },
    {
      'id': 3,
      'name': 'Mentored Spring 2018',
      'created_at': '2017/12/07 17:55:00 +0000',
      'archived': true,
      'questions': [
        {
          'id': 3,
          'form_id': 3,
          'question_text': 'Check the classes you have taken:',
          'question_type': 'Checkbox',
          'options': "['CS61A', 'CS61B', 'CS61C']",
          'order_number': 0,
        },
        {
          'id': 4,
          'form_id': 3,
          'question_text': 'Why CodeBase?',
          'question_type': 'Paragraph',
          'options': '',
          'order_number': 1,
        },
      ],
      'categories': [
        {
          'id': 3,
          'form_id': 3,
          'name': 'Received',
        },
        {
          'id': 4,
          'form_id': 3,
          'name': 'Accepted',
        },
      ],
    },
  ],
};

Response Properties

• forms: List of form objects

GET /applications

Gets a list of paginated application objects filtered on a given set of URL parameters. By default the applications should be sorted by date, newest first.

Filters

The following filters are input as URL parameters, e.g. for the filter page=4, the filtering is done by transforming the request URL to /applications?page=4.

• q: A string to search for in the applicant's name or email. (optional)
• category: The ID of the category to filter for. (optional)
• page: The index of the paginated results to return. If not given, assume this is page 1.

Example response (GET /applications?category=1&page=1):

{
  'page': 1,
  'num_pages': 3,
  'applications': [
    {
      'id': 1,
      'category_id': 1,
      'email': '[email protected]',
      'first_name': 'Andrew',
      'last_name': 'Chan',
      'read': false,
      'answers': {
        '1': {
          'id': 1,
          'application_id': 1,
          'question_id': 1,
          'answer_text': "['CS61A', 'CS61B']",
        },
        '2': {
          'id': 2,
          'application_id': 1,
          'question_id': 2,
          'answer_text': 'Because all the members are really smart and good looking',
        },
      },
    },
    {
      'id': 2,
      'category_id': 1,
      'email': '[email protected]',
      'first_name': 'Brian',
      'last_name': 'DeLeonardis',
      'read': false,
      'answers': {
        '3': {
          'id': 3,
          'application_id': 2,
          'question_id': 1,
          'answer_text': "['CS61A']",
        },
        '4': {
          'id': 4,
          'application_id': 2,
          'question_id': 2,
          'answer_text': "Because it's super cool and awesome",
        },
      },
    },
  ]
};

Response Properties

• page: The index of the paginated results returned
• num_pages: Total number of pages in the filtered query
• applications: List of application objects