API

[dgilge]

How shall we create the API URLs in a proper way? Every level should make sense and be uesd and it has to be unique, of course. I'm refering to the internal API (frontend JS), but we should have in mind to also provide an external API (apps, other websites, we could even support Core API, YAML, XML, MessagePack). What I have so far:

Work: .../ List of all (public) works ?language=en&author=Andy

See here for the article.

Suggestion from Lukas:

• /de/egw/sc/ returns details concerning book Steops to Christ
• /de/egw/sc/3/ returns book Steps to Christ page 3
• /de/egw/sc/3/1/ returns book Steps to Christ page 3, 1. paragraph

Concern from my side:

• Is it better to follow the known format book page.paragraph, e.g. SC1.1? This would result in de/egw/SC1.1/.
• What if we have an author called John Wyclif (/de/jw/) and Johannes Walter (/de/jw2/)? This isn't intuitive anymore. Therefore my suggestions: de/white/ellen_gould/ or de/ellen_g_white/ to prevent this numbering.
• I'd include the trustee. But in which order?

[lhermann]

This subject here is important. Let's tackle the different parts separately:

As a general rule I would suggest to only use lowercase lettering, slash separators, hyphenated-case and trailing slash.

Language

Language as two letter code is probably the best, and als unique. Is it better to prepend /de/author/book/ or append /author/book/de/?

Author

Initials egw are not unique indeed and will lead to unintuitive numbering. Another option would be last name only white, this is more international but suffers from the same problem of not being unique. Does it have to be unique? If yes we probably should use the entire name. I would suggest hyphenated-case ellen-g-white.

Book Chapter/Section Page Paragraph

/SC1.1/ is traditional, but not consistent. Additionally we have to distinguish page based numbering from chapter/section based numbering. /sc/page/1/ and /sc/chapter/1/ would be simple, but quite verbose. Maybe /sc/p/1/ for pages and /sc/p/1/1/ for page 1 paragraph 1 and /sc/ch/1/ for chapters and /sc/ch/1/1/ for chapter 1 paragraph 1; this way we never conflict pages with paragraphs, have a nice and short api and simply define the second number as paragraph.

Other

What is <trustee_code>?

[dgilge]

I ended up to seperate the private and public API (as you can see in api.md).

Private

The advantage of using the ID is that you have one lookup field in the db only which is indexed. You don't have any related fields you have to filter on. Thereby I think that's best for the private usage because we'll have a lot requests from the front end.

Public

The public API should look nicer. There we can use your suggetion.

Answers

I thougt that every trustee might have a trustee_code, e.g. Review and Herald rh. But we might not need it.

The author doesn't have to be unique, just the whole API URL. It's just a matter of probability.

[lhermann]

The idea of the private API is genius! Since the system will work entirely with id's, we can skip the human readable step completely. My comments were only related to the public API