lirmm
REST API returned answers documentation
The returned answers of the REST API is not documented. I start a first grammar document (not perfect, unsorted and incomplete) of the expected answers. WavesRestApiGrammar.txt
WavesRestApiGrammar.md
WAVES REST API returns
jobs
list
list all jobs of the user
JOBS_LIST=list(JOB_SHORT*)
JOB_SHORT=OrderedDict(
'url': URL
'slug':UID
'title':STR
'service':URL
'submission':URL
'client':MAIL
'status':STATUS
'created':TIMESTAMP
'updated':TIMESTAMP
'last_message':MSG
)
STATUS=OrderedDict(
'code':STATUS_CODE
'label':STR
)
MSG=OrderedDict(
'timestamp':TIMESTAMP
'message':STR
)
TIMESTAMP=YYYY-MM-ddThh:mm:ss.ssssssGMT
GMT=(+|-)hh:mm
UID=STR
MAIL=STR
STATUS_CODE=INT
read
details of a specific job
JOBS_READ=DETAILED_JOB
DETAILED_JOB=OrderedDict(
'url':URL
'slug':UID
'title':STR
'service':URL
'submission':URL
'client':MAIL
'status':STATUS
'created':TIMESTAMP
'updated':TIMESTAMP
'inputs':VAL_INPUTS
'outputs':VAL_OUTPUTS
'history':list(HISTORY_ENTRY*)
'last_message':MSG
)
VAL_INPUTS=OrderedDict(VAL_INPUT*)
VAL_INPUT=INPUT_NAME:VAL_INPUT_PARAM
INPUT_NAME=STR
VAL_INPUT_PARAM=VAL_INPUT_PARAM_FILE
|VAL_INPUT_PARAM_TEXT
|VAL_INPUT_PARAM_DECIMAL
|VAL_INPUT_PARAM_INT
#TODO:Complet all possible valued inputs param type
VAL_INPUT_PARAM_FILE=OrderedDict(
'param_type':'file'
'name':STR
'value':BASENAME_STR
'label':STR
'url':URL
)
VAL_INPUT_PARAM_TEXT=OrderedDict(
'param_type':'text'
'name':STR
'value':TEXT_VALUE
'label':STR
)
VAL_INPUT_PARAM_DECIMAL=OrderedDict(
'param_type':'decimal'
'name':STR
'value':FLOAT_STR
'label':STR
)
VAL_INPUT_PARAM_INT=OrderedDict(
'param_type':'int'
'name':STR
'value':INT_STR
'label':STR
)
BASENAME_STR=STR
TEXT_VALUE=STR
FLOAT_STR=STR #float in a string
INT_STR=STR #int in a string
VAL_OUTPUTS=OrderedDict(VAL_OUTPUT*)
VAL_OUTPUT=OUTPUT_NAME:VAL_OUTPUT_PARAM
VAL_OUTPUT_PARAM=OrderedDict(
'label':STR
'file_name':BASENAME_STR
'extension':FILE_EXTENSION
'url':URL|NONE
)
FILE_EXTENSION=STR #if not empty string, begin with '.'
HISTORY_ENTRY=OrderedDict(
'status_txt':STR
'status_code':STATUS_CODE
'timestamp':TIMESTAMP
'message':STR
)
delete
delete a job from job list
JOBS_DELETE=NONE
cancel
cancel a none finished job
TODO:JOBS_CANCEL=NONE?
inputs
List all inputs values of a job
JOBS_INPUTS=VAL_INPUTS
input
content of an input file
JOBS_INPUT=FILE_CONTENT
FILE_CONTENT=STR
outputs
List all output values of a job
JOBS_OUTPUTS=VAL_OUTPUTS
output
content of an ouput file
JOBS_OUTPUT=FILE_CONTENT
services
submissions
jobs
read
list all jobs of a user for a submission
SERVICES_SUBMISSIONS_JOBS_READ:list(JOB_SHORT*)
create
create a new jobs
SERVICES_SUBMISSIONS_JOBS_CREATE:#TODO:NONE ?
submission_form
The HTML form of the submission
SERVICES_SUBMISSIONS_SUBMISSION_FORM:HTML_FORM #Only form, not a valid HTML page
TODO : seems to be formated to be used with bootcamp.
SERVICES_SUBMISSIONS_SUBMISSION_FORMis for services.submissions.submission_form not for services.submissions.submission.form
list
List all available services
SERVICES_LIST=list(SERVICES_SHORT*)
SERVICES_SHORT=OrderedDict(
'url':URL
'name':STR
'version':VERSION_NUM
'short_description':STR
'service_app_name':STR
'jobs':URL
'submissions':list(SUBMISSION_VSHORT*)
'form':URL
'created':URL
'updated':URL
)
VERSION_NUM=STR #int.(int.)*int
SUBMISSION_VSHORT=OrderedDict(
'url':URL
'submission_app_name':STR
)
read
A single service informations
SERVICES_READ=SERVICES_SHORT
form
The HTML form of the first submission of the service.
SERVICES_FORM=HTML_FORM #Only form, not a valid HTML page
TODO : seems to be formated to be used with bootcamp.
jobs
list of the job of the user for this service
SERVICES_JOBS=list(JOB_SHORT)
submission
detail of a submission
SERVICES_SUBMISSION=DETAILED_SUBMISSION
submissions_list
list of detailed Submission of a services
SERVICES_SUBMISSIONS_LIST=list(DETAILED_SUBMISSION*)
DETAILED_SUBMISSION=OrderedDict(
'service':URL
'name':STR
'submission_app_name':STR
'form':URL
'jobs':URL
'inputs':INPUTS_FORM
'outputs':OUTPUTS_FORM
)
INPUTS_FORM=OrderedDict(INPUT_FORM*)
INPUT_FORM=INPUT_FORM_NAME:INPUT_FORM_DETAIL
INPUT_FORM_NAME=STR
INPUT_FORM_DETAIL=INPUT_FORM_DETAIL_LIST
|INPUT_FORM_DETAIL_FILE
|INPUT_FORM_DETAIL_INT
|INPUT_FORM_DETAIL_DECIMAL
|INPUT_FORM_DETAIL_TEXT
#TODO : to complete all possibilites
INPUT_FORM_DETAIL_LIST=OrderedDict(
'label':STR
'default':STR|NONE
'type':'list'
'mandatory':BOOL
'description':STR
'multiple':BOOL
'edam_formats':NONE|STR #TODO:Maybe String or list of a valid edam_format reference
'edam_datas':NONE|STR #TODO:Maybe String or list of a valid edam_data reference
('dependent_inputs':DEPENDENT_INPUTS_LIST)?
'values_list':INPUT_FORM_DETAIL_LIST_VALUES_LIST
)
INPUT_FORM_DETAIL_LIST_VALUES_LIST=OrderedDict(
'labels'=list(STR*)
'values'=list(STR*)
)#Same number of labels than values
INPUT_FORM_DETAIL_FILE=OrderedDict(
'label':STR
'default':STR|NONE
'type':'file'
'mandatory':BOOL
'description':STR
'multiple':BOOL
'edam_formats':NONE|STR #TODO:Maybe String or list of a valid edam_format reference
'edam_datas':NONE|STR #TODO:Maybe String or list of a valid edam_data reference
'max_size':INT
'allowed_extensions':EXTENSIONS_REGEX
#TODO : dependent_inputs ?
)
INPUT_FORM_DETAIL_INT=OrderedDict(
'label':STR
'default':STR|NONE
'type':'int'
'mandatory':BOOL
'description':STR
'multiple':BOOL
'edam_formats':NONE|STR #TODO:Maybe String or list of a valid edam_format reference
'edam_datas':NONE|STR #TODO:Maybe String or list of a valid edam_data reference
'min_val':INT|NONE
'max_val':INT|NONE
#TODO : dependent_inputs ?
)
INPUT_FORM_DETAIL_DECIMAL=OrderedDict(
'label':STR
'default':STR|NONE
'type':'decimal'
'mandatory':BOOL
'description':STR
'multiple':BOOL
'edam_formats':NONE|STR #TODO:Maybe String or list of a valid edam_format reference
'edam_datas':NONE|STR #TODO:Maybe String or list of a valid edam_data reference
'min_val':FLOAT|NONE
'max_val':FLOAT|NONE
#TODO : dependent_inputs ?
)
INPUT_FORM_DETAIL_TEXT=OrderedDict(
'label':STR
'default':STR|NONE
'type':'text'
'mandatory':BOOL
'description':STR
'multiple':BOOL
'edam_formats':NONE|STR #TODO:Maybe String or list of a valid edam_format reference
'edam_datas':NONE|STR #TODO:Maybe String or list of a valid edam_data reference
'mzx_length':INT
#TODO : dependent_inputs ?
)
EXTENSIONS_REGEX=STR #'*' for all extension
DEPENDENT_INPUTS_LIST=list(DEPENDENT_INPUT*)
DEPENDENT_INPUT<extend(INPUT_FORM_DETAIL)>=OrderedDict( #TODO: find a better way to write this.
'when_value':STR
...
)
OUTPUTS_FORM=OrderedDict(OUTPUT_FORM*)
OUTPUT_FORM=OUTPUT_FORM_NAME:OUTPUT_FORM_DETAIL
OUTPUT_FORM_NAME=STR
OUTPUT_FORM_DETAIL=OrderedDict(
'label':STR
'name':STR
'file_name':FORMATED_FILE_NAME
'help_text':STR
'edam_format':NONE|STR #TODO:Maybe String of a valid edam_format reference
'edam_data':NONE|STR #TODO:Maybe String of a valid edam_data reference
'issued_from':INPUT_FORM_NAME
)
FORMATED_FILE_NAME=STR #%s is remplaced by the 'issued_from' input value.
SERVICES_SUBMISSIONS_LISTis for service.submissions_list not for service.submissions.list
Thank you for this grammar, will have a look and integrate into our documentation if possible.
@CVroland , @marcoooo Hi, I am messing up with OpenAPI (SwaggerHub) and would like to practice and contribute to this project by making a documentation. Would be nice if I can help you somehow with that.
Hi there, I'm new to GitHub. While I've done aspects of technical writing in previous job roles, I'm now looking to get into technical writing professionally, which is why I'm trying to find open source RESTful API projects to help contribute documentation towards. I was wondering if you might have any issues that you may still need some help with?
Hi there, I'm new to GitHub. While I've done aspects of technical writing in previous job roles, I'm now looking to get into technical writing professionally, which is why I'm trying to find open source RESTful API projects to help contribute documentation towards. I was wondering if you might have any issues that you may still need some help with?
Well, every hand is welcome on this project, so if you'd like to contribute in any way, you are more than welcome to do so! Especially for API documentation. Tell me how I can help you.