search

TraCES-Lexicon / lexicon

Geez lexicon of the TraCES project
1 stars 0 forks source link

api documentation #4

Open PietroLiuzzo opened 7 years ago

PietroLiuzzo commented 7 years ago

define api for lexicon, with format of api call and responses

/lexicon/{term}

analysis, root, variants, passages

PietroLiuzzo commented 7 years ago

Goal

document lexicon functions to allow reuse by third party applications

Main actor(s)

applications developers

Short description

Each possible request, its format, the format of the response should be properly documented for reuse by third parties

Examples

a swagger documentation might be ok.

6

Preconditions

The lexicon needs to be an available web service with an accessible API. No password should be needed to use the service

sdruskat commented 7 years ago

Re https://github.com/TraCES-Lexicon/lexicon/issues/4#issue-221552533, as we deal with response objects assembled on the fly, I think instead of using /lexicon/{term} (which would point to existing resources following usual API logic), the API should simply define /lexicon as the root object, and then /lexicon/query?string=ረዓድ?format=fidael or /lexicon/query?string=ረዓድ?translit=false, where query is a GET.

PietroLiuzzo commented 7 years ago

ok

sdruskat commented 7 years ago

In fact, there are two options in handling Fidäl vs transliteration queries:

  1. Either front-end or back-end will have to figure out if they're dealing with one or the other, probably based on Unicode range, or
  2. The front-end provides two different, mutually exclusive widgets (text fields I guess) which capture the different strings separately.

As for usability, either option has its pros and cons. Having just one query field for user input may either confuse the user, or is deduplicating input possibilities.

Option 1 will mean that we have to decide whether to encode this in the front-end or the back-end, and this choice will also influence the API call arguments (if the back-end is to figure this out anyway, there's no use in providing a format or translit (boolean) argument).

Option 2 means that either a format or translit (boolean) argument can be used, or that we split the possibilities into two calls, e.g., query?fidaelstring=... and query?translitstring=....

Either option is fine by me, do you want to figure that one out in collaboration with the rest of the team (who may have opinions about the GUI design), @PietroLiuzzo, and we discuss downstream options from there?

PietroLiuzzo commented 7 years ago

I do not think this kind of thing needs further discussion than the one everyone can follow and comment on here. I would go for option 2 with default on translit=false as it sounds to me the easiest. we will then need to test anyway that this is true and alert in the gui if the string does not match the argument stated.

sdruskat commented 7 years ago

Agreed.

I'll leave checking for string validity to you (front-end) then.

On my end (API & back-end) I will prepare to receive queries in the forms /lexicon/query?string=ረዓድ&translit=false and
/lexicon/query?string=sometransliteratedstring&translit=true.

PietroLiuzzo commented 7 years ago

https://app.swaggerhub.com/apis/sdruskat/traces-lexicon-api/1.0.0-SNAPSHOT#/default/get_query