REST API returned answers documentation

[CVroland]

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_FORM is 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_LIST is for service.submissions_list not for service.submissions.list

[marcoooo]

Thank you for this grammar, will have a look and integrate into our documentation if possible.

[omelianlevkovych]

@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.

[ivosam2]

I would also like to contribute on API documentation :)

[Silks-road]

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?

[marcoooo]

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.

[sushmitha-manjunatha]

Hi there, I would like to contribute to documentation as well. I have previous experience as technical writer but took a break for personal reasons. Please let me know how to go about being part of documentation.