Developer documentation

API endpoint examples

documentation with examples of a few API endpoints that are not clear enough in the swagger docs.

PUT /coaches/{id}/update_status/

the endpoint expects the fields is_admin, is_active in the request body.
note that both these fields are optional

request body example:

{
  "is_admin": true,
  "is_active": false
}

the endpoint returns no data.

POST /projects/{id}/suggest_student/

the endpoint expects the following fields, student, skill and reason in the request body.
note that reason is optional and can be left empty
note that the skill must be a required skill of the project

request body example:

{
  "student": ".../api/students/1/",
  "skill": ".../api/skills/2/",
  "reason": "a reason"
}

the endpoint returns the project suggestion data that was created along with coach data

response body example:

{
  "student": ".../api/students/1/",
  "coach": {
    "url": ".../api/coaches/1/",
    "id": 1,
    "first_name": "admin",
    "last_name": "admin"
  },
  "skill": ".../api/skills/2/",
  "reason": "a reason"
}

POST /projects/{id}/remove_student/

the endpoint expects the following fields, student, coach and skill in the request body.

request body example:

{
  "student": ".../api/students/1/",
  "skill": ".../api/skills/2/",
  "coach": ".../api/coaches/1/"
}

the endpoint returns no data

POST /students​/{id}​/make_suggestion​/

the endpoint expects the following fields, suggestion and reason in the request body.
note that reason is optional and can be left empty
note that suggestion must be one of the following: 0 (yes), 1 (no), 2 (maybe)

request body examples:

{
  "suggestion": "0",
  "reason": "a reason",
}

{
  "suggestion": 1
}

the endpoint returns the suggestion data that was created along with coach data

response body example:

{
  "suggestion": "0",
  "reason": "a reason",
  "coach": {
    "url": ".../api/coaches/1/",
    "id": 1,
    "first_name": "admin",
    "last_name": "admin"
  }
}

DELETE ​/students​/{id}​/remove_suggestion​/

this endpoint expects no data
it removes the suggestion made by the user for the current student
it also return no data

POST ​/students​/{id}​/make_final_decision​/ and DELETE ​/students​/{id}​/remove_final_decision​/

these endpoints are functionally the same as /students​/{id}​/make_suggestion​/ and /students​/{id}​/remove_suggestion​/, but they create a final decision instead of a suggestion
only admins are allowed to do this

GET ​/projects​/get_conflicting_projects​/

this endpoint expects no data
it returns all project that conflict with another one

response body example:

{
  "conflicts": {
    ".../api/students/2/": [
      ".../api/projects/9/",
      ".../api/projects/6/"
    ],
    ".../api/students/4/": [
      ".../api/projects/5/",
      ".../api/projects/7/"
    ],
    ".../api/students/5/": [
      ".../api/projects/8/",
      ".../api/projects/11/"
    ]
  }
}

Tally integration

To integrate with Tally (a platform to build and share forms), our application provides a custom class (TallyForm). This class is able to validate forms and transform them to a more suitable object from which other (model) objects can be created (as demonstrated in the tallyregistration endpoint).

To validate and transform a Tally form, a JSON file with rules about the structure of the form is used. We call this the questions file.

Structure of questions file

root
|
|- index
|  |- question
|     |- attributes
|- index
|  |- question
|     |- attributes
|- ...

The questions file consists of multiple indexed question objects (each with their own unique attributes). TallyForm compares these objects against the questions in the Tally form and transforms them where necessary.

{
  "0": {
    "question": [
      "Are there any responsibilities you might have which could hinder you during the day?"
    ],
    "field": "hinder_work",
    "type": "TEXTAREA",
    "required": false
  },
  "0": {
    "question": [
      "Birth name"
    ],
    "field": "first_name",
    "type": "INPUT_TEXT",
    "required": true
  }
}

Example of a questions file with two questions.

Question object

A question object has different attributes. Some attributes are required and others are optional.

1. Question

A list of questions from the Tally form that need to be mapped to this question object. This attribute is required.

"question": ["What is your name?", "Wat is uw naam?"]

2. Field

Field in the database that corresponds to this question object. This attribute is required.

"field": "name"

3. Type

A string or a list of strings corresponding with the type of the questions from the Tally form. This attribute is required.

"type": ["TEXTINPUT", "MULTIPLE_CHOICE", "CHECKBOXES"]

4. Value

The answer of the question from the Tally form gets transformed into this value. This attribute is optional, if it is not present the answer from the Tally form is used.

"value": true

If the type of the question object is MULTIPLE_CHOICE or CHECKBOXES, answers becomes a required attribute. Answers is a list of answer objects.

• answer

An answer object has a required answer attribute that corresponds with a choice from the Tally form question. This object can also have a value attribute. It is possible to let this value point to the answer of another question in the Tally form. You can also specify if certain (required) question objects need to be skipped when this answer is selected.

"answers": [
      {
        "answer": "A professional Bachelor"
      },
      {
        "answer": "An academic Bachelor",
        "value": "academic bachelor"
      },
      {
        "answer": "An associate degree"
      },
      {
        "answer": "A master's degree"
      },
      {
        "answer": "Doctoral degree"
      },
      {
        "answer": "No diploma, I am self taught",
        "skip": [ 17, 18, 19 ]
      },
      {
        "answer": "Other",
        "value": {
          "question": [ "What kind of diploma are you currently going for?" ],
          "type": "INPUT_TEXT"
        }
      }
]

5. Required

A question can be required or optional. If the question is optional, it may have a null value. This attribute is required.

"required": false