openapi: 3.0.0 info: title: ClydeAPI description: This is the Clyde's api documentation.
Each endpoints are organised by endpoints **AND** by extensions making it easier to navigate. version: 0.0.1 servers: - url: https://clyde.herisson.ovh/api description: default api point for clyde's service tags: - name: default - name: General description: General endpoints - name: Ext (scientific articles) description: Scientifics articles extension's endpoints - name: Ext (Schedule) description: Schedule extension's endpoints - name: Ext (Student Registration) description: Student Registration's endpoints - name: Ext (Messaging) description: Messaging extension's endpoints paths: /ping: get: summary: Check the API status responses: default: description: pong content: text/plain: schema: type: string example: pong # Messaging /forum: get: summary: get list of available forum security: - bearer: [] tags: - Ext (Messaging) - Forum responses: '200': description: OK content: application/json: schema: type: array items: type: object required: - id - name - owner properties: id: type: integer name: type: string owner: type: integer description: user id of the teacher '401': $ref: '#/components/responses/UnauthorizedError' post: summary: Create a new forum security: - bearer: [] tags: - Ext (Messaging) - Forum requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: type: string courseId: type: integer responses: '201': description: User created '401': $ref: '#/components/responses/UnauthorizedError' /forum/{forumId}: parameters: - name: forumId in: path description: Id of the forum required: true schema: type: integer get: summary: get informations about a forum tags: - Ext (Messaging) - Forum responses: '200': description: OK content: application/json: schema: type: array items: type: object required: - id - name - owner properties: id: type: integer name: type: string owner: type: integer description: user id of the teacher topics: type: array items: type: object properties: id: type: integer name: type: string autor: type: integer description: user Id registered: description: List of registered user only if have the authorisation to view type: array items: type: integer description: userId '401': $ref: '#/components/responses/UnauthorizedError' delete: summary: remove the forum security: - bearer: [] tags: - Ext (Messaging) - Forum responses: '201': description: Forum deleted '401': $ref: '#/components/responses/UnauthorizedError' /forum/{forumId}/topic: parameters: - name: forumId in: path description: Id of the forum required: true schema: type: integer get: summary: list topics of a forum tags: - Ext (Messaging) - Forum responses: '200': description: OK content: application/json: schema: type: array items: type: object required: - id - name - author properties: id: type: integer name: type: string author: type: integer description: user id of the author '401': $ref: '#/components/responses/UnauthorizedError' post: summary: create a new topic in the forum tags: - Ext (Messaging) - Forum requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: subject: type: string content: type: integer responses: '201': description: post created '401': $ref: '#/components/responses/UnauthorizedError' /forum/{forumId}/topic/{topicId}: parameters: - name: forumId in: path description: Id of the forum required: true schema: type: integer - name: topicId in: path description: Id of the topic required: true schema: type: integer get: summary: get info about a topic tags: - Ext (Messaging) - Forum responses: '200': description: OK content: application/json: schema: type: object required: - id - name - author - locked properties: id: type: integer name: type: string author: type: integer description: user id of the author locked: type: boolean description: define if the topic is locked to new responses or not '401': $ref: '#/components/responses/UnauthorizedError' delete: summary: delete a topic security: - bearer: [] tags: - Ext (Messaging) - Forum responses: '201': description: Topic deleted '401': $ref: '#/components/responses/UnauthorizedError' /forum/{forumId}/topic/{topicId}/response: parameters: - name: forumId in: path description: Id of the forum required: true schema: type: integer - name: topicId in: path description: Id of the topic required: true schema: type: integer get: summary: list responses of a topic tags: - Ext (Messaging) - Forum responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer author: type: integer description: user id of the author content: type: string '401': $ref: '#/components/responses/UnauthorizedError' post: summary: create a new response tags: - Ext (Messaging) - Forum requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: content: type: integer responses: '201': description: Message posted '401': $ref: '#/components/responses/UnauthorizedError' /forum/{forumId}/topic/{topicId}/response/{responseId}: parameters: - name: forumId in: path description: Id of the forum required: true schema: type: integer - name: topicId in: path description: Id of the topic required: true schema: type: integer - name: responseId in: path description: Id of the response required: true schema: type: integer get: summary: get info on a response tags: - Ext (Messaging) - Forum responses: '200': description: OK content: application/json: schema: type: object required: - id - author - content properties: id: type: integer author: type: string content: type: integer '401': $ref: '#/components/responses/UnauthorizedError' delete: summary: delete a response tags: - Ext (Messaging) - Forum responses: '201': description: Message deleted '401': $ref: '#/components/responses/UnauthorizedError' /discussion: get: summary: get list of available discussions tags: - Ext (Messaging) - discussion responses: '201': description: OK content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string users: type: array items: type: integer '401': $ref: '#/components/responses/UnauthorizedError' post: summary: create a new discussion tags: - Ext (Messaging) - discussion requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: type: string users: type: array description: id of users items: type: integer responses: '201': description: Discussion created '401': $ref: '#/components/responses/UnauthorizedError' /discussion/{id}: parameters: - name: id in: path description: Id of the discussion required: true schema: type: integer get: summary: get info on a discussion tags: - Ext (Messaging) - discussion responses: '200': description: OK content: application/json: schema: type: object required: - id - name - users properties: id: type: integer name: type: string users: type: integer description: user ids of participants '401': $ref: '#/components/responses/UnauthorizedError' /discussion/{id}/msg: parameters: - name: id in: path description: Id of the discussion required: true schema: type: integer get: summary: list messages in a discussion tags: - Ext (Messaging) - discussion responses: '200': description: Ok content: application/json: schema: type: array items: type: object properties: id: type: integer datetime: type: integer author: type: integer content: type: string '401': $ref: '#/components/responses/UnauthorizedError' post: summary: post a new message in a discussion tags: - Ext (Messaging) - discussion requestBody: required: true content: application/x-www-form-urlencoded: schema: type: string description: message content responses: '201': description: Message sent '401': $ref: '#/components/responses/UnauthorizedError' /discussion/{id}/msg/{msgId}: parameters: - name: id in: path description: Id of the discussion required: true schema: type: integer - name: msgId in: path description: Id of the message required: true schema: type: integer get: summary: get info about message tags: - Ext (Messaging) - discussion responses: '200': description: Ok content: application/json: schema: type: object properties: id: type: integer datetime: type: integer author: type: integer content: type: string '401': $ref: '#/components/responses/UnauthorizedError' delete: summary: delete a message security: - bearer: [] tags: - Ext (Messaging) - discussion responses: '201': description: Message deleted '401': $ref: '#/components/responses/UnauthorizedError' /appointment: get: summary: list appointments tags: - Ext (Messaging) - appointment parameters: - name: type in: query required: false schema: type: string enum: [open, closed] responses: '200': description: Ok content: text/calendar: schema: type: string application/json: schema: type: array items: type: object properties: id: type: integer teacher: type: integer student: type: integer date: type: integer status: type: string '401': $ref: '#/components/responses/UnauthorizedError' post: summary: create a new appointment tags: - Ext (Messaging) - appointment requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: content: type: integer datetime: type: integer to: type: integer description: user id of the person to request to responses: '201': description: Appointment created '401': $ref: '#/components/responses/UnauthorizedError' /appointment/{id}: parameters: - name: id in: path description: Id of the appointment required: true schema: type: integer get: summary: get info on an appointment tags: - Ext (Messaging) - appointment responses: '200': description: Ok content: text/calendar: schema: type: string application/json: schema: type: object properties: id: type: integer teacher: type: integer student: type: integer date: type: integer status: type: string '401': $ref: '#/components/responses/UnauthorizedError' post: summary: Accept, decline or propose a new schedule for the appointment tags: - Ext (Messaging) - appointment requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: action: type: string enum: [accept, refuse, propose] data: type: object description: context dependant response (can be null) responses: '201': description: Done '401': $ref: '#/components/responses/UnauthorizedError' # general /users: get: summary: list all users tags: - General - SI security: - bearer: [] parameters: - in: query name: type required: false schema: $ref: '#/components/schemas/Roles' responses: '200': description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/User" '401': $ref: '#/components/responses/UnauthorizedError' /user: get: summary: get informations about yourself tags: - General - Users security: - bearer: [] responses: '200': description: Ok content: application/json: schema: $ref: "#/components/schemas/User" '401': $ref: '#/components/responses/UnauthorizedError' post: summary: Create user tags: - General - Users requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: LastName: type: string FirstName: type: string Email: type: string Address: $ref: "#/components/schemas/Address" BirthDate: type: string description: Follow the iso 8601 ("YYYY-MM-DD") Role: $ref: "#/components/schemas/Roles" example: { "LastName": "Doe" , "FirstName": "John", "Email": "John.Doe@example.com", "Address": { "Address": "Rue de Tournais 42", "Country": "BE"}, "BirthDate": "1941-02-22", "Role": "student" } responses: '201': description: User created '401': $ref: '#/components/responses/UnauthorizedError' patch: summary: Change informations about yourself tags: - General - Users security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/User' responses: '201': description: Successfully changed. '401': $ref: '#/components/responses/UnauthorizedError' /user/{RegNo}: parameters: - name: RegNo in: path description: Regestration number of the user (unique id) required: true schema: type: integer get: summary: Get user's informations tags: - General - Admin responses: '200': description: User found content: application/json: schema: $ref: "#/components/schemas/User" patch: summary: Alter user's informations tags: - General - Admin - Secretariat - Ext (scientific articles) security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/User' responses: '201': description: Successfully changed '401': $ref: '#/components/responses/UnauthorizedError' /course: post: summary: Create new course tags: - General - Courses - Secretariat security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: type: string courses: type: array items: type: string responses: '201': description: course created '401': $ref: '#/components/responses/UnauthorizedError' /courses/{id}: parameters: - name: id in: path required: true schema: type: integer get: summary: see courses informations tags: - General - Courses responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Course' delete: summary: delete a course tags: - General - Courses - Secretariat security: - bearer: [] responses: '201': description: Success '401': $ref: '#/components/responses/UnauthorizedError' patch: summary: Change course options tags: - General - Secretariat - Courses security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: type: string credits: type: integer faculty: type: string teachers: type: integer description: Teacher's identifier assistants: type: array items: $ref: '#/components/schemas/User' example: { "name": "Math pour l'info", "credits": 11, "faculty": "science", "Teacher": , "Assistants": [ ] } responses: '201': description: Course modified '401': $ref: '#/components/responses/UnauthorizedError' /cursus: post: summary: Create a cursus tags: - General - Cursus security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: type: string courses: type: array items: type: integer description: id of courses example: { "name": "Bac1", [] } responses: '201': description: Cursus created '401': $ref: '#/components/responses/UnauthorizedError' /cursus/{id}: get: summary: See Cursus's informations tags: - General - Cursus responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Cursus' parameters: - name: id in: path required: true schema: type: integer delete: summary: Delete cursus tags: - General - Cursus security: - bearer: [] responses: '201': description: Success '401': $ref: '#/components/responses/UnauthorizedError' patch: summary: Modify cursus tags: - General - Cursus security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: type: string credits: type: integer faculty: type: string teachers: $ref: '#/components/schemas/User' assistants: type: array items: $ref: '#/components/schemas/User' example: { "name": "Math pour l'info", "credits": 11, "faculty": "science", "Teacher": , "Assistants": [ ] } responses: '201': description: Cursus modified '401': $ref: '#/components/responses/UnauthorizedError' /Requests/{type}: get: summary: Give an array of every requests of the specified type tags : - Requests - SI - Ext (Student Registration) responses : '200': description : OK content : application/json : schema : type : array items : allOf: - type : object properties : id : type : integer - oneOf : - $ref : '#/components/schemas/RRRequest' - $ref : '#/components/schemas/SSRequest' - $ref : '#/components/schemas/UnRegRequest' - $ref : '#/components/schemas/ExempRequest' - $ref : '#/components/schemas/RegRequest' discriminator: propertyName : type parameters: - name: type in: path description: type of the request required: true schema: type: integer post : summary: create a request tags : - Requests - Guest - Student - Ext (Student Registration) security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: oneOf: - $ref : '#/components/schemas/RRRequest' - $ref : '#/components/schemas/SSRequest' - $ref : '#/components/schemas/UnRegRequest' - $ref : '#/components/schemas/ExempRequest' - $ref : '#/components/schemas/RegRequest' discriminator: propertyName : type responses: '201': description: New request created '401': $ref : '#/components/responses/UnauthorizedError' /Requests/{type}/{id}: parameters: - name: type in: path description: type of the request required: true schema: type: integer - name : id in : path description: id of the selected Request required : true schema : type : integer get : summary : Get all the data composing a request tags : - Requests - SI - Teacher - Ext (Student Registration) responses : '200': description : OK content : application/json : schema : allOf: - type : object properties : id : type : integer - oneOf : - $ref : '#/components/schemas/RRRequest' - $ref : '#/components/schemas/SSRequest' - $ref : '#/components/schemas/UnRegRequest' - $ref : '#/components/schemas/ExempRequest' - $ref : '#/components/schemas/RegRequest' discriminator: propertyName : type patch: summary: Change the state of request tags: - Requests - SI - Teacher - Ext (Student Registration) security: - bearer: [] requestBody: required : true content: application/x-www-form-urlencoded: schema: oneOf : - $ref : '#/components/schemas/RRRequest' - $ref : '#/components/schemas/SSRequest' - $ref : '#/components/schemas/UnRegRequest' - $ref : '#/components/schemas/ExempRequest' - $ref : '#/components/schemas/RegRequest' discriminator: propertyName : type responses: '201': description: State modified '401': $ref: '#/components/responses/UnauthorizedError' /lesson: post: summary: create a new lesson tags: - Secretariat - Lesson - Ext (Schedule) security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: date: type: string description: Follow the iso 8601 ("YYYY-MM-DD") CourseId: type: integer duration: type: number classroom: type: string responses: '201': description: Lesson created '401': $ref: '#/components/responses/UnauthorizedError' /lesson/{id}: parameters: - name: id in: path required: true schema: type: integer get: summary : See lesson's informations tags: - Users - Lesson - Ext (Schedule) responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Lesson' patch: summary : Modify Lesson tags: - Secretariat - Lesson - Ext (Schedule) security: - bearer: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: date: type: string description: Follow the iso 8601 ("YYYY-MM-DD") IDcourse: type: integer duration: type: number classroom: type: string responses: '201': description: Lesson modified '401': $ref: '#/components/responses/UnauthorizedError' delete: summary: Delete lesson tags: - Lesson - Secretariat - Ext (Schedule) security: - bearer: [] responses: '201': description: Success '401': $ref: '#/components/responses/UnauthorizedError' /scheduleRequest: post: summary: Create a new request tags: - Teacher - ScheduleRequest - Ext (Schedule) requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: requestType: type: string lessonId: type: integer newDate: type: string description: Follow the iso 8601 ("YYYY-MM-DD") newClassroom: type: string newCourseId: type: integer responses: '201': description: Request created '401': $ref: '#/components/responses/UnauthorizedError' /scheduleRequest/{id}: parameters: - name: id in: path required: true schema: type: integer get: summary : See request information tags: - Teacher - Secretariat - ScheduleRequest - Ext (Schedule) responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ScheduleRequest' patch: summary : Modify request tags: - Teacher - ScheduleRequest - Ext (Schedule) requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: newDate: type: string newClassroom: type: string newCourseId: type: integer responses: '201': description: Request modified delete: summary: Delete request tags: - Teacher - Secretariat - ScheduleRequest - Ext (Schedule) responses: '201': description: Success /display: post: summary: Create a new display tags: - Display - Ext (Schedule) requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: timeMode: type: string displayMode: type: string userId: type: integer responses: '201': description: display created /display/{id}: parameters: - name: id in: path required: true schema: type: integer get: summary : See display information tags: - Users - Display - Ext (Schedule) responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Display' patch: summary : Modify display tags: - Users - Display - Ext (Schedule) requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: timeMode: type: string displayMode: type: string responses: '201': description: Display modified # Extension publication scientifique /article: post: summary: create an article tags: - Ext (scientific articles) - Researcher security: - bearer : [] responses: "201" : description: OK '401': $ref: '#/components/responses/UnauthorizedError' requestBody: required : true content: application/json: schema: type: object properties: pdf: type: string description : the B64 version encoding of the pdf file access: type: string summary: type: string language: type: string title: type: string date: type: string description: Follow the iso 8601 ("YYYY-MM-DD") views: type: integer example: { "access": "private", "pdf": " *the b64 encoding of the pdf* ", "summary": "looks in details about graph's second theorem", "language": "english", "title": "graph's second theorem study", "date":"2023-02-01", "views": 420, "authors" : [] } /article/{id}: parameters: - name: id in: path required: true schema: type: integer get: summary: get a certain article tags: - Users - Ext (scientific articles) security: - bearer: [] responses: "201": description: OK content: application/json: schema: $ref: '#/components/schemas/Article' '401': $ref: '#/components/responses/UnauthorizedError' patch: summary: modify an article tags: - Researcher - Ext (scientific articles) security: - bearer : [] responses: "201": description: article modifié '401': $ref: '#/components/responses/UnauthorizedError' requestBody: required : true content: application/json: schema: type: object properties: pdf: type: string description : the B64 version encoding of the pdf file access: type: string summary: type: string language: type: string title: type: string date: type: string description: Follow the iso 8601 ("YYYY-MM-DD") views: type: integer example: { "access": "public", "pdf": " *the new b64 encoding of the pdf* ", "summary": "looks in details about the duck's algorithm problem", "language": "english", "title": "duck's algorithm problem solving", "date":"2023-02-01", "views": 10, "authors" : [] } delete: summary: delete own article tags: - Researcher - Ext (scientific articles) security: - bearer: [] responses: '201': description: OK '401': $ref: '#/components/responses/UnauthorizedError' /DisplayArticle: parameters: - in: query name: author required: false schema: type: string - in: query name: access required: false schema: type: string enum: [public, restricted, private] - in: query name: name required: false schema: type: string get: summary: get a list of article's data tags: - Users - Guest - Ext (scientific articles) responses: '200': description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/DisplayArticle" components: securitySchemes: bearer: type: http scheme: bearer schemas: User: type: object properties: regNo: type: integer photo: type: object lastName: type: string firstName: type: string email: type: string address: $ref: "#/components/schemas/Address" birthDate: type: string description: Follow the iso 8601 ("YYYY-MM-DD") role: $ref: '#/components/schemas/Roles' example: { "regNo": 42, "lastName": "Doe" , "firstName": "John", "email": "John.Doe@example.com", "address": { "address": "Rue de Tournais 42", "country": "BE"}, "birthDate": "1941-02-22", "role": "student" } Address: type: object properties: address: type: string country: type: string description: Follow the ISO-3166-1 alpha-2 standard. example: { "address": "Rue de Tournais 42", "country": "BE" } Course: type: object properties: id: type: integer name: type: string credits: type: integer faculty: type: string teachers: type: integer description: user's id assistants: type: array items: type: integer description: user's id example: { "id": 42, "name": "Math pour l'info", "credits": 11, "faculty": "science", "Teacher": 42, "Assistants": [ ] } Cursus: type: object properties: id: type: integer name: type: string courses: type: array items: type: string example: { "id": 42, "courses": ['Math', 'Info'] } Roles: type: string enum: [teacher, student, secretary] RegRequest: type : object properties: Name : type: string Firstname : type : string Address : $ref: "#/components/schemas/Address" Email: type : string BirthDate: type : string description: Follow the iso 8601 ("YYYY-MM-DD") Cursus: type : integer description : ID of a specific cursus Photo: type : string description: Path of the picture that the user uploaded IdentityCard: type : string description: Path of the picture of the user's identity card Degree: type : string description: Path of the pdf containing the user's degree Certificate: type : string description: Path of the pdf containing the user's admission certificate (optionnal) ForeignerCertificate: type : string description: Path of the pdf containing the user's foreigner certificate (optionnal) State: type : string RRRequest: type : object properties : RegNo : type : integer NewCursusid : type : integer State : type : string SSRequest: type : object properties : RegNo : type : integer Amount : type : integer Document : type : string description : justification document for a scholarship UnRegRequest : type : object properties : RegNo : type : integer State : type : string ExempRequest : type : object properties : RegNo : type : integer Courseid : type : integer State : type : string Article: type: object properties: articleId: type: integer access : type : string pdf : type : string description : file location summary: type : string language: type : string title : type : string date: type : string views : type : integer authors: type: array items: $ref: '#/components/schemas/User' description: first user is the author, the remaining users are co-authors example: { "articleId": 42, "access": "private", "pdf": "/articles/42", "summary": "looks in details about graph's second theorem", "language": "english", "title": "graph's second theorem study", "date":"2023-02-01", "views": 420, "authors" : [] } DisplayArticle: type: object properties: articleId: type: integer access: type: string summary: type: string title: type: string author: type: string items: $ref: '#/components/schemas/User' example: { "articleId": 42, "access": "private", "summary": "looks in details about graph's second theorem", "title": "graph's second theorem study", "author" : "john doe" } Lesson : type: object properties: id: type: integer date: type: string description: Follow the iso 8601 ("YYYY-MM-DD") duration: type: number description: duration of a course in hours classroom: type: string courseId: type: integer example: { "id": 12, "date": "2023-12-01", "duration": 1.5, "classroom": "AMPHI01", "courseId": 12 } ScheduleRequest: type: object properties: id: type: integer requestType: type: string lessonId: type: integer teacherId: type: integer newDate: type: string description: Follow the iso 8601 ("YYYY-MM-DD") newClassroom: type: string newCourseId: type: integer example: { "id": 12, "requestType": "moveLesson", "lessonId": 52, "teacherId": 12, "newDate": "2023-12-20", "newClassroom":, "newCourseId":, } Display: type: object properties: id: type: integer timeMode: type: string description: Define the period displayed on the schedule (week,month,quadrimester..) displayMode: type: string userId: type: integer description: Id of the user who owns this display example: { "id": 12, "timeMode": "month", "displayMode": "grid", "UserId": 12 } responses: UnauthorizedError: description: Unauthorized access or missing bearer