API Documentation Improvement

[kavitharaju]

Requesting UI teams who refer the API documentations (on swagger or redoc ) to use this discussion space for parking your suggestions on improvements on the documentation.
If you see

• incorrect explanations
• missing details
• lack of clarity

or any such points where you have a suggestion on how things could be improved, please let us know here.

[RevantCI]

Add source label as array to the swagger documenationin the get, put and post calls request and response examples

• https://api.vachanengine.org/docs#/Sources/get_source_v2_sources_get
• https://api.vachanengine.org/docs#/Sources/edit_source_v2_sources_put
• https://api.vachanengine.org/docs#/Sources/add_source_v2_sources_post

[RevantCI]

Some sugeestions can be added to the swagger documentation regarding validitity of fields like

• Language code is not 3 lettter but BCP valid code , add a sample eg. - kgo-x-krongoabdalla
• Version - Abbreviation as uppercase alphabets without spaces
• License - Enter Code as alphanumeric without spaces

[RevantCI]

When doing put calls for source data like commentarie we could including ids in the put calls to make unique row dentification easier so that we can ensure the correct record gets updated and can be verified in the UI. Else the UI app needs to calculate what are the unique identifer fields and send put calls accordingly. For bible we are used to using book Code but for other content type it would help make it clearer.

• https://api.vachanengine.org/docs#/Bibles/edit_bible_book_v2_bibles__source_name__books_put
• https://api.vachanengine.org/docs#/Commentaries/edit_commentary_v2_commentaries__source_name__put
• https://api.vachanengine.org/docs#/Dictionaries/edit_dictionary_word_v2_dictionaries__source_name__put
• https://api.vachanengine.org/docs#/Infographics/edit_infographics_v2_infographics__source_name__put
• https://api.vachanengine.org/docs#/Bible%20Videos/edit_biblevideo_v2_biblevideos__source_name__put