The following document details the recurring data format used when communicating with a GlobaLeaks node.

Goal

using this object as base for the client-server communication, would be much more easy:

• Maintain and operate in the communication (client-server, server-client) in a more structured way.
  • external software developer has to develop client handling a limited set of data, recurring in the entire REST specification
  • patches and update would be applied in a single piece of code, avoiding dependencies from the software complexities
  • Provide a version tracked communication system. Along with the objects, also the version of the specific is tracked, therefore newer software may detect and fallback on the old specified formats.
• Use a validation model based on the data format, so in whatsoever input the backend may receive, would be able to perform security checks before accept that input, independently from the media
• Make no mistake in assigning values to the objects (every elements has a type defined, and is regular expression checked when a new assignment is performed)

simple data elements

• receiverID: 'r_[a-zA-Z]{20,20}$'
• contextID: 'c_[a-zA-Z]{20,20}$'
• tipID: 't_[a-zA-Z]{50,50}$'
• moduleID: 'm_\d{10,10}$'
• submissionID: 's_[a-zA-Z]{50,50}$'
• folderID: 'f_[a-zA-Z]{20,20}$'
• receiptID: '\d{10,10}$'
• string: '\w'
• int: '\d'
• bool: True or False
• moduleENUM: (notification|delivery|inputfilter)
• commentENUM: (your|external|whistleblower)
• time: to be defined

complex data elements

Those elements has a shared prefix -Dict.

• fileDict: used to describe every file, completed and partial

  "filename": "string"
  "file_description": "string"
  "size": "int"
  "content_type": "string"
  "date": "time"
  "cleaned_meta_data": "bool"
  "completed": "bool"
  

• folderDict

  "fID": "folderID"
  "folder_name": "string"
  "folder_description": "string"
  "download_performed": "int"
  "files": [ "fileDict" ]
  

• receiverDescriptionDict

  "rID": "receiverID"
  "CanDeleteSubmission": "bool"
  "CanPostponeExpiration": "bool"
  "CanConfigureNotification": "bool"
  "CanConfigureDelivery": "bool"
  "CanTriggerEscalation": "bool"
  "ReceiverLevel": "int"
  "receiver_name": "string"
  "receiver_description": "string"
  "receiver_tags": "string"
  "creation_date": "time"
  "last_update_date": "time"
  "LanguageSupported": [ "string" ]
  

• nodePropertiesDict

  "AnonymousSubmissionOnly": "bool"
  

• adminStatisticsDict

  "hours_interval": "int"
  "download_number": "int"
  "receiver_accesses": "int"
  "submission_received": "int"
  

• publicStatisticsDict

  "active_contexts": "int"
  "active_receivers": "int"
  "uptime_days": "int"
  

• formFieldsDict

  "presentation_order": "int"
  "label": "string"
  "name": "string"
  "required": "bool"
  "hint": "string"
  "type": "string"
  "value": "string"
  

• moduleDataDict

  "mID": "moduleID"
  "active": "bool"
  "module_type": "moduleENUM"
  "name": "string"
  "module_description": "string"
  "service_message": "string"
  "admin_options": [ formFieldsDict ]
  "user_options": [ formFieldsDict ]
  

• contextDescriptionDict

  "cID": "contextID"
  "name": "string"
  "context_description": "string"
  "creation_date": "time"
  "update_date": "time"
  "fields": [ formFieldsDict ]
  "SelectableReceiver": "bool"
  "receivers": [ receiverDescriptionDict ]
  "EscalationTreshold": "int"
  "LanguageSupported": [ "string" ]
  

• commentDescriptionDict

  "writtentext": "string"
  "commenttype": "commentENUM"
  "author": "string"
  "date": "time"
  

• tipIndexDict

   "cID": "contextID"
   "tiplist": [tipSubIndex ]
  

• tipSubIndex

  "tID": "tipID"
  "tip_title": "string"
  "notification_adopted": "string"
  "delivery_adopted": "string"
  "download_limit": "int"
  "access_limit": "int"
  "access_performed": "int"
  "expiration_date": "time"
  "creation_date": "time"
  "last_update_date": "time"
  "comment_number": "int"
  "folder_number": "int"
  "overall_pertinence": "int"
  

• tipDetailsDict

  "tip": tipSubIndex
  "tip_data": [ formFieldsDict ]
  "folder": [ folderDict ]
  "comment": [ commentDescriptionDict ]
  "receiver_selected": [ receiverDescriptionDict ]
  

• localizationDict

How to upate/change those things:

• suppose that you need a specific field, the operative sequence to maintain aligned the various code are:
  • detect with structure you need to modify
  • goes in recurringtypes and put the "define" properly. If is not part of a recurringtypes, but is part of answers.py or requests.py, change them.
  • goes in the appropriate dummy file, and update with spurious data
  • update this file, with a little of description of the field usage (what's are the information source, if not explicit, and if need to be managed in some special way)