IFS06-variazioni-iscrizioni.yaml

openapi: 3.0.0
info:
  title: IFS06 - Changes in academic enrolments/ Variazioni nelle iscrizioni accademiche
  x-summary: | 
    Retrieve the changes in academic enrollments / Ottiene le variazioni delle iscrizioni accademiche
  version: 2.1.0
  description: |
        Retrieve the changes in academic enrollments / Ottiene le variazioni delle iscrizioni accademiche
  contact:
    name: Institute name
    email: formal.institute@email.it
  x-api-id: 00000000-0000-0000-0000-000000000000
  termsOfService: 'http://swagger.io/terms/'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
paths:
  '/student-enrollments-changes':
    post:
      summary: | 
        Retrieve the "fingerprints (hash codes)" of all students' enrollments in the last three academic years to identify changes in the recipient's perspective. / 
        Acquisizione delle "impronte (codifica hash)" di tutte le iscrizioni delle studentesse/degli studenti negli ultimi tre anni accademici al fine di identificarne le variazioni dal punto di vista del fruitore
      tags:
        - IFS06.1 - student-enrollments-changes
      security: [{}]
      responses:
        '200':
          description: Request successfully executed / Richiesta eseguita con successo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/student-enrollments-changes'
              examples:
                Exist a next page (cursor is valued) :
                  value:
                    data:
                      institute_code: C6
                      last_update: '2023-10-13T17:32:28Z'
                      enrollments_hash:
                        - key: '8e44f796d7478a135c226598939d56a5b0d9405210235d4845ed158a7fec7535'
                          hash: '56c3880bfcc4df0e35780c805d9ec942bbb8b4e237c1b63c6f2688cb58ef0a3a'
                        - key: 'AAAAf796d7478a135c226598939d56a5b0d9405210235d4845ed158a7fec7535'
                          hash: '56c3880bfcc4df0e35780c80sdlkjljiirpepw85830t3j85jg0fj054fj04jf03'
                        - key: 'BBBBf796d7478a135c226598939d56a5b0d9405210235d4845ed158a7fec7535'
                          hash: 'df8340f834tr8f3j84fj48jf83fngooero45305jf30l04k0r43kfd043kdew34t'
                    meta:
                      cursor: '6eyJpZCI6M57'
                The last page (cursor is not valued):
                  value:
                    data:
                      institute_code: C6
                      last_update: '2023-10-13T17:32:28Z'
                      enrollments_hash:
                        - key: '8e44f796d7478a135c226598939d56a5b0d9405210235d4845ed158a7fec7535'
                          hash: '56c3880bfcc4df0e35780c805d9ec942bbb8b4e237c1b63c6f2688cb58ef0a3a'
                        - key: 'p9sndsh75636d7478a135c226598939d56b0d94052102oiasdh7632bbc78h843'
                          hash: '56c3880bfcc4df0e35780c80sdlkjljiirpepw85830t3j85jg0fj054fj04jf03'
                        - key: 'qmane9vsd7cksad8e44f7978a135c226598939d56a5b0d94052102gh9msabv9s'
                          hash: 'df8340f834tr8f3j84fj48jf83fngooero45305jf30l04k0r43kfd043kdew34t'
                    meta:
                      cursor: null      
        '400':
          description: <b>Bad Request</b> - il server non può elaborare la richiesta del client a causa di una sintassi errata o di una richiesta non valida. <br> Esempi di cause
            <br> - Richiesta non valida
            <br> - Sintassi errata
            <br> - Parametro mancante
            <br> - Richiesta incompleta
            <br> - ...
        '500':
          description: Internal server error / Errore interno del server 
      operationId: student-enrollments-changes
      description: |
        * Returning the information reduced to a 'hash (SHA256)' for each student in the form (key, value), where the key is the hash of the student's social security number and the value is the hash of the student's enrollment. 
        * Restituisce le informazioni ridotte in "hash (SHA256)" per ogni studente/studentessa nella forma (chiave, valore), dove la chiave è l'hash del codice fiscale dello studente e il valore è l'hash delle sue iscrizioni.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/enrollments_request'
            examples:
              Invocazioni successive alla prima (paginazione):
                value:
                  cursor: fowfio543s     
          application/xml:
            schema:
              type: object
              additionalProperties: false
              properties: {}
        description: |
          PUNTO DI ATTENZIONE:
          * Il campo cursor Indica il valore del cursore restituito dalla chiamata;
          * Da NON valorizzare durante la prima invocazione;
          * Da valorizzare nelle invocazioni successive (laddove presente);

      parameters: []
  /status:
    get:
      summary: Verifica stato delle API (Health Check)
      security: [{}]
      operationId: check-status
      description: Check the system's health status / Verificare lo stato di salute del sistema 
      tags:
        - health-check
      responses:
        '400':
          description: Bad Request
        '204':
          description: The service is running correctly / Il servizio è in esecuzione correttamente
        '500':
          description:  The service is not running. / Il servizio non è in esecuzione. 
components:
  headers:
    Retry-After:
      description: |-
        Retry contacting the endpoint *at least* after seconds.
        See https://tools.ietf.org/html/rfc7231#section-7.1.3
      schema:
        format: int32
        maximum: 186400
        minimum: 0
        type: integer
    X-RateLimit-Limit:
      description: The number of allowed requests in the current period / Numero di richieste consentite nel periodo attuale
      schema:
        format: int32
        maximum: 1000000
        minimum: 0
        type: integer
    X-RateLimit-Remaining:
      description: The number of remaining requests in the current period / Numero di richieste rimanenti nel periodo attuale 
      schema:
        format: int32
        maximum: 1000000
        minimum: 0
        type: integer
    X-RateLimit-Reset:
      description: The number of seconds left in the current period / Numero di secondi rimanenti nel periodo attuale
      schema:
        format: int32
        maximum: 186400
        minimum: 0
        type: integer
  schemas:
    enrollments_request:
      type: object
      additionalProperties: false
      description: Request the list of active courses offered by the Institute in an academic year. / Richiedi la lista dei corsi attivi offerti dall'Istituto in un anno accademico.
      properties:
        cursor:
          type: string
          description: Cursor / Cursore
          example: 'fowfio543s'
          nullable: true
          minLength: 1
          maxLength: 512
        institute_code:
          type: string
          description: Institute identification code / Codice identificativo dell’istituto  
          example: 'AA'          
          minLength: 1
          maxLength: 256
          nullable: true
    student-enrollments-changes:
      additionalProperties: false
      type: object
      description: Returning the information reduced to a 'hash (SHA256)' for each student in the form (key, value), where the key is the hash of the student's social security number and the value is the hash of the student's enrollment. / Restituisce le informazioni ridotte in "hash (SHA256)" per ogni studente/studentessa nella forma (chiave, valore), dove la chiave è l'hash del codice fiscale dello studente e il valore è l'hash delle sue iscrizioni.
      properties:
        data:
          $ref: '#/components/schemas/data'
        meta:
            $ref: '#/components/schemas/meta'
      required:
        - data
        - meta
    meta:
      nullable: true
      type: object
      additionalProperties: false
      description: Informazioni del cursore
      properties:
        cursor:
          type: string
          description: Cursor / Cursore
          example: 'fowfio543s'          
          minLength: 1
          maxLength: 512
          nullable: true
    data:
      type: object
      additionalProperties: false
      description: Personal data of the student / Dati personali della studentessa o dello studente
      properties:
        institute_code:
          type: string
          description: Institute identification code / Codice identificativo dell’istituto
          example: 'C3'          
          minLength: 1
          maxLength: 256
          nullable: true
        last_update:
          type: string
          format: date-time
          description: Timestamp of last update / Data ultimo aggiornamento
          example: '2023-10-13T17:32:28Z'

        enrollments_hash:
          type: array
          minItems: 0
          description: List of enrollments for student / Elenco iscrizioni di una studentessa o di uno studente
          items:
            $ref: '#/components/schemas/enrollments_hash'
    enrollments_hash:
      type: object
      additionalProperties: false
      description: Detailed enrollment information / Informazioni dettagliate sull'iscrizione
      properties:
        key:
          type: string
          description: Hash tax code / Hash del codice fiscale
          example: '8e44f796d7478a135c226598939d56a5b0d9405210235d4845ed158a7fec7535'
          minLength: 64
          maxLength: 64
        hash:
          type: string
          description: Enrollments hash code / Codice hash delle iscrizioni
          example: '9bc4e295f51d940db6d7a9ca01059ace00376d4feed10225c592e010a780a8d5'
          minLength: 64
          maxLength: 64
      required:
        - key
        - hash
  requestBodies: {}
  responses: {}
servers:
  - url: 'https://localhost:8080/api'
    description: localhost
tags:
  - name: IFS06.1 - student-enrollments-changes
  - name: health-check