Update API documentation

[fsteeg]

• Autosuggest with sample like: http://lobid.org/api#auto-suggest-examples, see https://github.com/hbz/lobid-organisations/issues/330
• Query string syntax, link to Lucene docs: https://lucene.apache.org/core/5_5_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package_description
• Scroll API for dumps like: http://lobid.org/api#pagination+limits+bulk-downloads, see https://github.com/hbz/lobid-resources/issues/330

[fsteeg]

Also: fix spelling: https://github.com/hbz/lobid-organisations/issues/331#issuecomment-288060704

[acka47]

We should also document possibility of greater/lesser than searches for integers (e.g. publication.startDate or describedBy.dateModified).

[fsteeg]

Sample documents should be in tabs, quoting @acka47 from https://github.com/hbz/lobid-resources/issues/357#issue-218136548:

Putting all the different resource types (Buch, Artikel, Periodikum, Serienband) one below the other at http://lobid.org/resources/api makes the page quite confusing. It would be great to have one example window with tabs for the different resource types.

[fsteeg]

Deployed to staging for resources: http://stage.lobid.org/resources/api

I suggest we review this for resources first, and then update the organisations documentation accordingly.

[ChristophEwertowski]

The "URL-Suche" under the headline "Abfragemöglichkeiten" doesn't lead to a result with resources. The query URL is also a different than the stated text of both behind "URL-Suche" and the written URL. Also I don't get the criteria for the suggestions. The suggestions for "Hein" (http://stage.lobid.org/resources/search?q=Hein&format=json%3Aagent) contain also "Karpeles, Gustav" which is a distance of 3 away from the query. (if that's the criterium). The rest is good.

[acka47]

Regarding "Bereichssuche": I find the use of < and > much more intuitive. For the given example, http://stage.lobid.org/resources/search?q=publication.startDate%3A%3C1501&format=json gives the same results.

Regarding auto-suggest:

• I second @ChristophEwertowski that some suggestions are quite strange and the ranking doesn't make much senese ("Karpeles" before "Heine").
• As far as I understand it, the GND ID lookup is based on the bibliographic records from hbz01 (so basically a lookup on all GND IDs that are in the lobid data). This should be made clear in the documentation I guess, to differ it from a general GND lookup (we have with the subject API).
• For subject and agent lookups, I suggest to also return the query string that delivers all resources with the respective agent/subject, e.g. for the subject example:

[
   {
      "label":"Arabisches Vollblut",
      "id":"http://d-nb.info/gnd/4068791-0",
      "query":"http://stage.lobid.org/resources/search?q=subject.componentList.id:http\:\/\/d\-nb.info\/gnd\/4068791-0",
      "category":"SubjectHeading"
   },
   {
      "label":"Pferd",
      "id":"http://d-nb.info/gnd/4045503-8",
      "query":"http://stage.lobid.org/resources/search?q=subject.componentList.id:http\:\/\/d\-nb.info\/gnd\/",
      "category":"SubjectHeading"
   },
   ...
]

For the

[acka47]

Regarding the example resources in a tab view: Although I like it, I am afraid that it breaks the basic documentation lookup behaviour which I believe to be this: I want to find information on a specific JSON key (e.g. volumeIn) so I go to the API page and search the page. I won't find it as the key is in the "Serienband" example tab. Analogous to this, when you have chosen a specific tab and click in the hypothes.is column on an annotation from another tab, you will jump to the beginning of the page and not to the actual annotated text.

I am afraid we have to switch this back.

[fsteeg]

Redeployed with most of your suggested changes: http://stage.lobid.org/resources/api

What I did not change:

First, I had two reasons for not documenting the < > syntax:

1. These are special cases of the more general [x TO y] syntax, which supports all kinds of ranges via * wildcards
2. It seems to be an Elasticsearch-specific feature, since it's not mentioned in the Lucene query DSL documentation we link to

Second, I don't think adding the query to the suggestions as you described makes sense, since it's only one way to query the data. We might as well use the label or the category. Also the label, id, and category format seems to be common for the jQuery autosuggest component we use.

One final issue regarding the sample annotations: one annotation now appears on one of the example queries, on contribution.age. It's actually for contributorOrder, no idea why it shows up on contribution.age. In this case, I think we can simply delete it, because contributorOrder is no longer used, correct? In general, and for the future, maybe it helps no annotate fields including the quotes, or even with the field value, to make the annotations as specific as possible.

[ChristophEwertowski]

I didn't found the example of the contribution.age / contribution.agent. Is it already removed? Otherwise +1

[acka47]

I already deleted the contributorOrder/contribution.age annotation.

Suggestions are way better now.

Second, I don't think adding the query to the suggestions as you described makes sense, since it's only one way to query the data. We might as well use the label or the category.

I don't see where using the category makes any sense here. Using the label might work but won't give the intended results if you only want results with the exact subject/agent identified during the lookup. Thus, I still think that these additions would be really helpful. We may discuss this tomorrow...

[acka47]

Otherwise, +1.

[fsteeg]

[...] Thus, I still think that these additions would be really helpful. We may discuss this tomorrow...

In any case, I'd say it's a different issue (change to suggestions format), separate from the API documentation. Given your +1 I'll deploy the updated API documentation.

[fsteeg]

Reopening for the lobid-organisations API documentation.