Skip to content
This repository has been archived by the owner on May 24, 2022. It is now read-only.

Developer documentation

Jump to bottom
Lennart edited this page May 14, 2022 · 11 revisions

API endpoint examples

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

coach endpoints

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.

project endpoints

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

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/"
    ]
  }
}

POST /projects/resolve_conflicts/

this endpoint expects a list of objects to resolve conflicts. each object should have a project, student, coach and skill. this will remove all projectsuggestions of the given project and student, but with a different skill and/or coach. in other words, it keeps only the projectsuggestion that matches the given object. the endpoint does this for all given object in the list.

note that all students in the objects should be unique, as only one student can be kept.

request body example:

[
  {
    "project": ".../api/projects/1/",
    "student": ".../api/students/2/",
    "coach": ".../api/coaches/1/",
    "skill": ".../api/skills/2/"
  },
  {
    "project": ".../api/projects/4/",
    "student": ".../api/students/4/",
    "coach": ".../api/coaches/1/",
    "skill": ".../api/skills/3/"
  }
]

the endpoint returns no data

student endpoints

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

POST /students/bulk_status/

with this endpoint, you can update the status of multiple students at once (in bulk). the endpoint expects one status (an integer) and a list of students, the status of all these students will then be changed to the given status.

request body examples:

{
  "status": "1",
  "students": [
    ".../api/students/8/",
    ".../api/students/10/",
    ".../api/students/6/"
  ]
}

{
  "status": 2,
  "students": [
    ".../api/students/1/"
  ]
}

the endpoint returns the request body data if it was successful

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?"]
  1. Field

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

"field": "name"
  1. 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"]
  1. 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"
        }
      }
]
  1. 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
Clone this wiki locally