How to work with associative table with additional attributes in REST?

Question

Imagine you have 3 entities: Student, Discipline and Alunodiscipline.

The entity AlunoDisciplina , in addition to relating the Aluno with the Disciplina, also includes other information, such as the student’s final grade. So basically we have something like this:

class AlunoDisciplina {
    Aluno aluno;
    Disciplina disciplina;
    double notaFinal;
}

The way the above entity is exposed, aluno and disciplina make up a composite primary key, since a student cannot be associated with the same discipline more than once.

Some operations I need to implement:

1. List of students enrolled in the course (with their grades);
2. List of subjects in which the student is enrolled (with their grades);
3. Add/Remove a student from a discipline;
4. Edit the student’s final grade in the discipline.

How can I expose this relationship Restful way?

---

What I thought so far

For items 1 and 2, respectively, I imagine the resources below.

(GET) /disciplines/{idDisciplina}/students-enrolled.json

{
    "alunosMatriculados": [{
        "aluno": {
            "id": 2,
            "nome": "Pedro"
        },
        "notaFinal": 9.5
    }, {
        "aluno": {
            "id": 6,
            "nome": "Maria"
        },
        "notaFinal": 10
    }]
}

(GET) /students/{idAluno}/disciplines.json

{
    "matriculadoNasDisciplinas": [{
        "disciplina": {
            "id": 1,
            "nome": "Matemática"
        },
        "notaFinal": 9.5
    }, {
        "disciplina": {
            "id": 2,
            "nome": "Filosofia"
        },
        "notaFinal": 7
    }]
}

For items 3 and 4 I am not finding the best way to solve.

The best solution would be this or is there some other better way?

Have any suggestions for items 3 and 4?

Answer 1

I believe that you can simplify the returns of methods 1 and 2, returning only a list instead of a complex object, I believe this would simplify your API

(GET) /disciplines/{idDiscipline}/students-enrolled.json

[
    {
        "id": 2,
        "nome": "Pedro"
        "notaFinal": 9.5,
    },
    {
        "id": 6,
        "nome": "Maria"
        "notaFinal": 10
    }
]

(GET) /students/{idAluno}/disciplines.json

[
    {
        "id": 1,
        "nome": "Matemática",
        "notaFinal": 9.5
    },
    {
        "id": 2,
        "nome": "Filosofia",
        "notaFinal": 7
    }
]

To remove, add a note or update a note, you can use the same URL but with different Method Definitions.

(POST) /alunos/disciplinas/
C. Body: idAluno=?&idDisciplina=? 
(DELETE) /alunos/disciplinas/
C. Body: idAluno=?&idDisciplina=? 
(PUT) /alunos/disciplinas/
C. Body: idAluno=?&idDisciplina=?&notaFinal=?

Remembering that this is just a suggestion