Refactor status endpoint mapping config

[nichtich]

This issue also applies to wikidata-jskos.

The number of possible configurations for mapping endpoints have grown so much, a refactoring of the data format returned by the /status endpoint is needed. The new format of key config.mappings would be a JSON object with access keys.

Value false or missing key means there is no mapping endpoint.

Value true, meaning there is a read-only mapping endpoint, is used as deprecated short form for

{
  "read": { "auth": false }
}

In addition to read the keys create, update, and delete can exist, all with the same possible structure. A missing key means its action is not supported at all (e.g. no delete). The structure supports three keys:

• auth (boolean) whether authentication is required to perform the action
• crossUser (boolean) whether mappings of other users can updated or deleted (might also be supported for read and create in the future but not now) (this field is currently auth.allowCrossUserEditing)
• identityProviders (array of string) which identity providers a user needs to have an account at to perform the action (this field is currently auth.identityProviders)
• identities (array of string) set of individual identity URIs that are allowed to perform this action (this field is currently auth.whitelist)

Example:

{
  "auth": true,
  "identityProviders": ["wikidata"],
  "crossUser": true
}

additional optional keys of config.mappings are

• fromSchemeWhitelist an array of concept scheme URIs that mappings are allowed to have in field fromScheme[].uri for write-operations (create and update)

• toSchemeWhitelist an array of concept scheme URIs that mappings are allowed to have in field toScheme[].uri for write-operations (create and update)

The whitelists should also apply for data import so they can also be guaranteed (if given) for read operation.

The config file format may support shortcuts such as true as shortcut for { "auth": false } or field write as alias for all of create, update and delete, but only for convenience of configuration:

{
  "read": true,
  "write": { "auth": true }
}

The /status endpoint should return the expanded form:

{
  "read": { "auth": false },
  "create": { "auth": true },
  "update": { "auth": true },
  "delete": { "auth": true },
}

[stefandesu]

Great writeup, thanks! Two things from my side:

1. Can we have a shortcut for identities and identityProviders that apply to all actions with auth? So maybe have some kind of inheritance from upper levels of the config object. Currently, there is no use case where we'd need to specify different values for different actions, and also it could be expanded so that clients get the full objects. Just so that we don't have three lists of identities to manage.

2. How do we deal with versioning? On our website, we have all the previous Cocoda versions still accessible, and some of them (1.0.0 and 1.0.1 in particular) will break if we introduce these changes.

[stefandesu]

On more thing: We are still missing the option whether the API supports saving creators, with wikidata-jskos as a use-case. Cocoda always shows Wikidata mappings as "not saved" because their creator has changed (from nothing to the current identity). Any ideas? I'd say either a specific key for this purpose (e.g. creatorAllowed), or more generally a list of disallowed properties or something like that.

[stefandesu]

2. How do we deal with versioning?

While I think it would probably be best to introduce proper API versioning to jskos-server (and therefore to wikidata-jskos as well), it would probably be easier to just add the old config keys to the expanded status response, inferred from the new config format. Of course that would bloat the status response, but if we introduced some way of versioning for the API, the "default" version would still need to be the current one because we can't rewrite old clients, so consuming the API from the browser for example would still return the old responses.

Also, we couldn't really do versioning in the URI because that would break all our mapping and annotation URIs, and using a header would not be accessible via a browser request. I don't think there is a good solution, only different compromises.

[nichtich]

On more thing: We are still missing the option whether the API supports saving creators, with wikidata-jskos as a use-case. Cocoda always shows Wikidata mappings as "not saved" because their creator has changed (from nothing to the current identity). Any ideas? I'd say either a specific key for this purpose (e.g. creatorAllowed), or more generally a list of disallowed properties or something like that.

Add a field anonymous to not include creator in mappings:

{
  "auth": true,
  "identityProviders": ["wikidata"],
  "crossUser": true,
  "anonymous": true
}

So crossUser means to allow to work on foreign mappings and anonymous disables sending a creator field in mappings. This could also be useful for privacy requirements the identity should only be used for authentification.

[nichtich]

1. Can we have a shortcut for identities and identityProviders that apply to all actions with auth?

Add any kind of configuration shortcuts as you like as long as the clients get an expanded form at /status so they don't need to know about the shortcuts.

[stefandesu]

So crossUser means to allow to work on foreign mappings and anonymous disables sending a creator field in mappings. This could also be useful for privacy requirements the identity should only be used for authentification.

I like this. 👍

Add any kind of configuration shortcuts as you like as long as the clients get an expanded form at /status so they don't need to know about the shortcuts.

Okay.

I'll start working on this as soon as we have decided how to deal with the versioning issue...

[stefandesu]

Implemented via 678d0a34fdc417b7bd144e9bc878961f4ca8dec4 (the issue tags got eaten because I had them on a separate line which was of course interpreted as a comment 🤦‍♂️). Please take a look at https://coli-conc.gbv.de/api/status to see if that's what you expected. Right now we still have the old keys in, but as soon as wikidata-jskos and Cocoda are updated accordingly, we should remove them. Together with #71 (and maybe one or two small other changes) we could then release it as 1.0.0.

Missing implementations here are still:

• [x] fromSchemeWhitelist
• [x] toSchemeWhitelist

Everything else should be properly implemented.