scraf.raml

#%RAML 1.0
---
title: Scraf
baseUri: https://scraf.pwrau.ml/api/{version}
version: v1

/students:
  type:
    collection:
      example-get-collection-name: "Andrea Pa"
      example-get-collection-response: |
        [
          {
            "id": 107,
            "name": "Andrea Pappacoda"
          },
          {
            "id": 238,
            "name": "Paolo Andreoli"
          }
        ]
  /{studentId}:
    type: collection-item
    /subjects:
      type: sub-collection-read
      /{subjectId}:
        /marks:
          type: sub-collection-read

/teachers:
  type:
    collection:
      example-get-collection-name: "Andrea Pa"
      example-get-collection-response: |
        [
          {
            "id": 107,
            "name": "Andrea Pappacoda"
          },
          {
            "id": 238,
            "name": "Paolo Andreoli"
          }
        ]
  /{teacherId}:
    type: collection-item
    /subjects:
      type: sub-collection
      /{subjectId}:
        type: sub-collection-item
        /marks:
          type: sub-collection-read

/schools:
  type:
    collection:
      example-get-collection-name: "Cobi"
      example-get-collection-response: |
        [
          {
            "code": "VBIS00700V",
            "name": "IS \"L. COBIANCHI\""
          },
          {
            "code": "FEIC823006",
            "name": "I.C. Obiante Blu"
          }
        ]
  /{schoolId}:
    type: collection-item
    /subjects:
      type:
        collection:
          example-get-collection-name: "Italiano"
          example-get-collection-response: |
            [
              {
                "code": "lingua-e-letteratura-italiana",
                "name": "Lingua e letteratura italiana"
              }
            ]
      /{subjectId}:
        type: collection-item
        /marks:
          type: collection
          /{markId}:
            type: collection-item
    /classes:
      type: collection
      /{classId}:
        type: collection-item
        /subjects:
          type: sub-collection
          /{subjectId}:
            type: sub-collection-read
        /students:
          /{studentId}:
        /teachers:
          /{teacherId}:
  /students:
    type: sub-collection
    /{studentId}:
      type: sub-collection-item
  /teachers:
    type: sub-collection
    /{teacherId}:
      type: sub-collection-item

resourceTypes:
  collection:
    description: <<resourcePathName>> registered to Scraf
    get:
      description: Get a list of <<resourcePathName>> based on their name
      queryParameters:
        name:
          description: "Name of the <<resourcePathName|!singularize>> to search"
          type: string
          minLength: 3
          required: true
          example: <<example-get-collection-name>>
      responses:
        200:
          body:
            application/json:
              type: <<resourcePathName>>-get-response
              example: <<example-get-collection-response>>
        400:
          body:
            application/json:
              type: message
              example: |
                {
                  "message": "The query must be at least 3 characters long"
                }
    post:
      description: Register a <<resourcePathName|!singularize>> and get its id
      body:
        application/json:
          type: <<resourcePathName>>-post-request
      responses:
        201:
          body:
            application/json:
              type: <<resourcePathName>>-post-response
              example: |
                {
                  "id": 107
                }
        400:
          body:
            application/json:
              type: message
              example: |
                {
                  "message": "The parameter \"paolo\" does not exist"
                }
  collection-item:
    get:
      description: Get details about a <<resourcePathName|!singularize>>
      responses:
        200:
          body:
            application/json:
              type: <<resourcePathName|!singularize>>-get-response
    patch:
      description: Change details about a <<resourcePathName|!singularize>>
      body:
        application/json:
          type: <<resourcePathName|!singularize>>-patch-request
      responses:
        200:
        400:
          body:
            application/json:
              type: message
              example: |
                {
                  "message": "The parameter \"paolo\" does not exist"
                }
    delete:
      description: Delete a <<resourcePathName|!singularize>>
      responses:
        200:
  sub-collection:
    get:
      description: Get the list of <<resourcePathName>> of a particular entity
      responses: 
        200:
          body:
            application/json:
              type: id-array
              example: |
                [
                  {
                    "id": 107
                  },
                  {
                    "id": 238
                  }
                ]
    post:
  sub-collection-item:
    delete:
  sub-collection-read:
    get:

types:
  students-get-response:  !include raml/student/collection-get-response.json
  students-post-request:  !include raml/student/collection-post-request.json
  students-post-response: !include raml/student/collection-post-response.json
  student-get-response:  !include raml/student/item-get-response.json
  student-patch-request: !include raml/student/item-patch-request.json

  teachers-get-response:  !include raml/teacher/collection-get-response.json
  teachers-post-request:  !include raml/teacher/collection-post-request.json
  teachers-post-response: !include raml/teacher/collection-post-response.json
  teacher-get-response:  !include raml/teacher/item-get-response.json
  teacher-patch-request: !include raml/teacher/item-patch-request.json

  schools-get-response:  !include raml/school/collection-get-response.json
  schools-post-request:  !include raml/school/collection-post-request.json
  schools-post-response: !include raml/school/collection-post-response.json
  school-get-response:  !include raml/school/item-get-response.json
  school-patch-request: !include raml/school/item-patch-request.json

  subjects-get-response:  !include raml/subject/collection-get-response.json
  subjects-post-request:  !include raml/subject/collection-post-request.json
  subjects-post-response: !include raml/subject/collection-post-response.json
  subject-get-response:  !include raml/subject/item-get-response.json
  subject-patch-request: !include raml/subject/item-patch-request.json

  id: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        }
      }
    }
  id-array: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          }
        }
      }
    }
  search-result: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  message: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  teacher-post: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "mail": {
          "type": "string",
          "format": "email"
        },
        "name": {
          "type": "string"
        },
        "surname": {
          "type": "string"
        }
      }
    }
  school-post: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    }
  class-post: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  subject-post: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  class: |
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }