RESTful APIs + Clean URLs for cologne

[drdhaval2785]

https://api.github.com/repos/drdhaval2785/siddhantakaumudi

Please look at the API structure of various links mentioned on this page. It is extremely intuitive. Can we design similar APIs for cologne where the URL itself sends necessary information and we send back the response JSON?

UPDATE

https://github.com/sanskrit-lexicon/Cologne/blob/master/api/apidoc.md is the place where I will be tracking various existing Cologne APIs and their rewrite rules.

[gasyoun]

@artforlife thanks. Please see https://github.com/sanskrit-lexicon/Cologne/issues/117#issuecomment-296415679 for comparison - a bigger list of possible URLs. And need to know your opinion on https://github.com/sanskrit-lexicon/Cologne/issues/117#issuecomment-306047026 as well.

The URL as you proposed is a possible solution. But there should be an alternative, twice shorter as described at https://github.com/sanskrit-lexicon/Cologne/issues/249#issuecomment-463042839 It's important.

[artforlife]

@funderburkjim, @gasyoun forwarded me your letter with "exercises." They seem straightforward. I have started on them, but need access to some repositories.

Here is what I sent to @gasyoun regarding this:

Regarding #1, I need access to the following repository from Jim: https://github.com/funderburkjim/apidev. That is the one to which I am trying to push from the server, to make sure the connection is set up properly.

Also, the DO server currently has the following in its /var/www/html/cologne/ directory:

apidev dictionary_init.sh hwnorm1c_init.sh sanhw1 test.php
apidev_init.sh gra mw test.html unixify.py

It is probably wise to ask Jim for access to the respective repositories as well. For example, I am pretty sure we will need it for "mw".

Could you help us with this? Let me know if you have questions about anything.

[artforlife]

Address-bar problem

Tried to do some research.

1. Enable proxy module on apache2

   1. sudo a2enmod proxy_http
   2. sudo a2enmod proxy
   3. sudo service apache2 restart

2. Add [P] flag at the end

At the end of it all, .htaccess reads like this

Options +FollowSymLinks -MultiViews
RewriteEngine On
RewriteBase /
RewriteEngine on
RewriteRule ^suggest/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]*) http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc2/query.php?word=&lastLnum=0&max=$5&filter=deva&regexp=exact&scase=true&sword=$4&sregexp=$2&transLit=$3&outopt=outopt4&swordhw=hwonly [P]
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]+)/$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/getword.php?key=$2&filter=$4&noLit=off&accent=$5&transLit=$3 [P]
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]+)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/getword.php?key=$2&filter=$4&noLit=off&accent=$5&transLit=$3 [P]
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/([^/]*)/$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/getword.php?key=$2&filter=$4&noLit=off&accent=no&transLit=$3 [P]
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/getword.php?key=$2&filter=$4&noLit=off&accent=no&transLit=$3 [P]
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/getword.php?key=$2&filter=deva&noLit=off&accent=no&transLit=$3 [P]
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/getword.php?key=$2&filter=deva&noLit=off&accent=no&transLit=$3 [P]
RewriteRule ^entries/([^/]*)/([^/]*)/$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/getword.php?key=$2&filter=deva&noLit=off&accent=no&transLit=slp1 [P]
RewriteRule ^entries/([^/]*)/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/getword.php?key=$2&filter=deva&noLit=off&accent=no&transLit=slp1 [P]
RewriteRule ^pdf/([^/]*)/word/([^/]*)$/ http://www.sanskrit-lexicon.uni-koeln.de/scans/awork/apidev/servepdf.php?dict=$1&key=$2 [P]
RewriteRule ^pdf/([^/]*)/word/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/awork/apidev/servepdf.php?dict=$1&key=$2 [P]
RewriteRule ^pdf/([^/]*)/page/([^/]*)$/ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/servepdf.php?page=$2 [P]
RewriteRule ^pdf/([^/]*)/page/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc/servepdf.php?page=$2 [P]
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]+)/$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=$4&accent=$5&viewAs=phonetic [P]
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]+)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=$4&accent=$5&viewAs=phonetic [P]
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/([^/]*)/$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=$4&accent=no&viewAs=phonetic [P]
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=$4&accent=no&viewAs=phonetic [P]
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=deva&accent=no&viewAs=phonetic [P]
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=deva&accent=no&viewAs=phonetic [P]
RewriteRule ^list/([^/]*)/([^/]*)/$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=slp1&serverOptions=deva&accent=no&viewAs=phonetic [P]
RewriteRule ^list/([^/]*)/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=slp1&serverOptions=deva&accent=no&viewAs=phonetic [P]

Are these URLs still current? Is this where we would like to go?

Is it possible to get sample calls for each URL on this list? That is, I would like a call with real-life parameters for each end-point, so I can test it locally and then on the testing server.

[drdhaval2785]

The URLs are still current. I am not sure whether we want to reach there or not. Marcis had strong reservations against long URLs. So it is not yet decided.

If you can shorten the left side of equations, better. Right side links mostly work.

word = rAma dict = MW translit = slp1

These seem to be reasonable parameters

[artforlife]

http://localhost/apitrial/entries/PW/slp1/citra/deva/ignoreaccent

I would go for http://www.sanskrit-lexicon.uni-koeln.de/MD/citra/SDI/ instead of http://www.sanskrit-lexicon.uni-koeln.de/scans/MDScan/2014/web/webtc/indexcaller.php

/SDI/

These service pages we will close for indexation. S for SLP1, D for devanagari, I for ignore accents.

I propose we do a two-stage roll-out. First, we implement URLs in their longer version. Once that is done, we can shorten them to the format you advocate. We should at least do this at the testing stage. This way it will be easier to control what we want and make changes. Once URL sequences are set, the shortening of words should be straightforward. The deployment to production can be done with the final version.

[drdhaval2785]

Seems a good idea. Let us do it that ways.

[artforlife]

@drdhaval2785 , @gasyoun , I am attaching the list of URLs as it appears to me after I parsed it and went over it. I would like you to double check it. I am particularly interested in knowing how you envision the calls to be made. Those are presented in the form of comments above each rewrite rule. Let us spec those out properly. Furthermore, the ones marked with a question mark deserve a closer look for one reason or another.

If I am missing something or if there are inaccuracies, let us clarify them before I move on with further work.

# 1. /suggest/sregexp/transLit/sword/max/
RewriteRule ^suggest/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]*) http://www.sanskrit-lexicon.uni-koeln.de/scans/$1Scan/2014/web/webtc2/query.php?word=&lastLnum=0&max=$5&filter=deva&regexp=exact&scase=true&sword=$4&sregexp=$2&transLit=$3&outopt=outopt4&swordhw=hwonly [P]

# 2.a. /entries/key/transLit/filter/accent/
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]+)/$ apidev/getword.php?key=$2&filter=$4&noLit=off&accent=$5&transLit=$3 [P]

# 2.b. /entries/key/transLit/filter/accent
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]+)$ apidev/getword.php?key=$2&filter=$4&noLit=off&accent=$5&transLit=$3 [P]

# 3.a. /entries/key/transLit/filter/
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/([^/]*)/$ apidev/getword.php?key=$2&filter=$4&noLit=off&accent=no&transLit=$3 [P]

# 3.b. /entries/key/transLit/filter
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/([^/]*)$ apidev/getword.php?key=$2&filter=$4&noLit=off&accent=no&transLit=$3 [P]

# 4.a /entries/key/transLit/
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)/$ apidev/getword.php?key=$2&filter=deva&noLit=off&accent=no&transLit=$3 [P]

# 4.b. /entries/key/transLit/
RewriteRule ^entries/([^/]*)/([^/]*)/([^/]*)$ apidev/getword.php?key=$2&filter=deva&noLit=off&accent=no&transLit=$3 [P]

# 5.a. /entries/key/
RewriteRule ^entries/([^/]*)/([^/]*)/$ apidev/getword.php?key=$2&filter=deva&noLit=off&accent=no&transLit=slp1 [P]

# 5.b. /entries/key
RewriteRule ^entries/([^/]*)/([^/]*)$ apidev/getword.php?key=$2&filter=deva&noLit=off&accent=no&transLit=slp1 [P]

# 6.a. /pdf/dict/word/key/
RewriteRule ^pdf/([^/]*)/word/([^/]*)$/ http://www.sanskrit-lexicon.uni-koeln.de/scans/awork/apidev/servepdf.php?dict=$1&key=$2 [P]

# 6.b. /pdf/dict/word/key
RewriteRule ^pdf/([^/]*)/word/([^/]*)$ http://www.sanskrit-lexicon.uni-koeln.de/scans/awork/apidev/servepdf.php?dict=$1&key=$2 [P]

# 7.a.(?) /pdf/page-variable/page/whatevs/
RewriteRule ^pdf/([^/]*)/page/([^/]*)$/ apidev/servepdf.php?page=$2 [P]

# 7.b.(?) /pdf/page-variable/page/whatevs
RewriteRule ^pdf/([^/]*)/page/([^/]*)$ apidev/servepdf.php?page=$2 [P]

# 8.a. /list/key/phoneticInput/serverOptions/accent/
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]+)/$ apidev1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=$4&accent=$5&viewAs=phonetic [P]

# 8.b. /list/key/phoneticInput/serverOptions/accent
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/([^/]*)/([^/]+)$ apidev1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=$4&accent=$5&viewAs=phonetic [P]

# 9.a. /list/key/phoneticInput/serverOptions/
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/([^/]*)/$ apidev1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=$4&accent=no&viewAs=phonetic [P]

# 9.b. /list/key/phoneticInput/serverOptions
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/([^/]*)$ apidev1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=$4&accent=no&viewAs=phonetic [P]

# 10.a. /list/key/phoneticInput/
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)/$ apidev1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=deva&accent=no&viewAs=phonetic [P]

# 10.b. /list/key/phoneticInput
RewriteRule ^list/([^/]*)/([^/]*)/([^/]*)$ apidev1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=$3&serverOptions=deva&accent=no&viewAs=phonetic [P]

# 11.a. /list/key/
RewriteRule ^list/([^/]*)/([^/]*)/$ apidev1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=slp1&serverOptions=deva&accent=no&viewAs=phonetic [P]

# 11.b. /list/key
RewriteRule ^list/([^/]*)/([^/]*)$ apidev1/listhier.php?key=$2&keyboard=yes&inputType=phonetic&unicodeInput=devInscript&phoneticInput=slp1&serverOptions=deva&accent=no&viewAs=phonetic [P]

[gasyoun]

Marcis had strong reservations against long URLs.

And still has.

First, we implement URLs in their longer version.

Sure

word = rAma
dict = MW
translit = slp1

These seem to be reasonable parameters

slp1 is good for several reasons and should be used by default in generating the URLs. What I say is:

word = rAma
dict = MW

Should be enough. Actually even MW can be used by default, in this case we can have only

word = rAma

without accent. The question is what should be the default display. SLP1 is good for URLs, but not for human reading. So display by default before choosing should be human readable - IAST or devanagari.

[artforlife]

Marcis had strong reservations against long URLs.

And still has.

First, we implement URLs in their longer version.

Sure

word = rAma
dict = MW
translit = slp1

These seem to be reasonable parameters

slp1 is good for several reasons and should be used by default in generating the URLs. What I say is:

word = rAma
dict = MW

Should be enough. Actually even MW can be used by default, in this case we can have only

word = rAma

without accent. The question is what should be the default display. SLP1 is good for URLs, but not for human reading. So display by default before choosing should be human readable - IAST or devanagari.

What is key and what is filter?

Can you fill in the first call's parameters fully, as an example?

/entries/key/transLit/filter/accent/

Also, on all of these we seem to be missing the dictionary parameter. Is that expected? The toy-example I made above used it: http://sites.dev/sanskrit-dict/cologne/api/mw/hari/slp1/iast

[gasyoun]

What is key and what is filter?

filter = output encoding for Sanskrit words key = dictionary headword

Can you fill in the first call's parameters fully, as an example?

/entries/key/transLit/filter/accent/

Yakov's string contains 5 elements, but getword.php?key=citra&filter=iast&noLit=off&transLit=slp1 has only 5. Your /entries/ equals to scans/PWScan/2014/web/webtc/

So

/entries/key/transLit/filter/accent/

would be

/PW/citra/slp1/deva/ignoreaccent/

http://www.sanskrit-lexicon.uni-koeln.de/apitest/entries/PW/slp1/citra/deva/ignoreaccent

redirects to (and is still a working example)

https://www.sanskrit-lexicon.uni-koeln.de/scans/PWScan/2014/web/webtc/getword.php?key=citra&filter=deva&noLit=off&transLit=slp1

Also, on all of these we seem to be missing the dictionary parameter. Is that expected? The toy-example I made above used it: http://sites.dev/sanskrit-dict/cologne/api/mw/hari/slp1/iast

As per seem to be missing the dictionary parameter - indeed, it's hidden inside scans/PWScan/2014/web/webtc/ and should it be a parameter at all? Not sure. I guess it would make sense to have such a parameter, than 33 real folders named after dicitonaries containing the index.php script doing the same job.

The only drawback seems to be the capital PW in the whole url. It is a bit difficult to modify it to lowercase in rewrite rule. Jim can handle it in backend. The dictionary code passed in small letters can be converted to capital on his part in PHP.

We will have capital letters in URL anyway, because SLP1 is the way I propose we code the key in URL string. So PW should not be an issue as well.

http://localhost/apitrial/entries/PW/slp1/citra/deva/ignoreaccent

@drdhaval2785 as stated bellow some thing can be taken for granted and should not be stated in all URLs. Instead of a long URL like the one quoted above I see:

http://localhost/apitrial/entries/PW/slp1/citra/

Where ignoreaccent is by deffault. If accent will be needed (we can add the field like a for accent). deva can be accepted as default as well. Althought slp1 could be taken away as well, leawing only dictionary and headword, we could play with capital letters in it.

SLP1 sLP1 - IAST output slP1 - with accent Slp1 -

And so on.