cocoda-sdk 3.5.0 → 3.6.1

package/README.md

@@ -6,29 +6,28 @@
 
 > SDK for [Cocoda](https://github.com/gbv/cocoda) and [coli-conc](https://coli-conc.gbv.de/) services
 
-## Table of Contents <!-- omit in toc -->
+## Table of Contents
+
 - [Install](#install)
 - [Usage](#usage)
   - [Import](#import)
-  - [v1 Compatibility](#v1-compatibility)
   - [Configuration](#configuration)
   - [Registries](#registries)
   - [Providers](#providers)
   - [Multiple Instances](#multiple-instances)
   - [Authenticated Requests](#authenticated-requests)
-- [Methods](#methods)
-  - [Methods for cocoda-sdk instance](#methods-for-cocoda-sdk-instance)
-  - [Registry Methods - General](#registry-methods---general)
-  - [Registry Methods - Concept Schemes](#registry-methods---concept-schemes)
-  - [Registry Methods - Concepts](#registry-methods---concepts)
-  - [Registry Methods - Concordances](#registry-methods---concordances)
-  - [Registry Methods - Mappings](#registry-methods---mappings)
-  - [Registry Methods - Annotations](#registry-methods---annotations)
-  - [Registry Methods - Various](#registry-methods---various)
-- [Errors](#errors)
+- [API](#api)
+  - [General](#general)
+  - [Concept Schemes](#concept-schemes)
+  - [Concepts](#concepts)
+  - [Concordances](#concordances)
+  - [Mappings](#mappings)
+  - [Annotations](#annotations)
+  - [Occurrences](#occurrences)
+  - [Types](#types)
+  - [Errors](#errors)
 - [Maintainers](#maintainers)
-- [Publish](#publish)
-- [Contribute](#contribute)
+- [Contributing](#contributing)
 - [License](#license)
 
 ## Install
@@ -36,7 +35,7 @@
 npm i cocoda-sdk
 ```
 
-We are also providing a browser bundle: https://cdn.jsdelivr.net/npm/cocoda-sdk@2/dist/cocoda-sdk.js (~51K gzipped, ~155K not gzipped) It will be available under the global name `CDK` and contain the listed members below (in particular the default instance `CDK.cdk`).
+We also provide a browser bundle <https://cdn.jsdelivr.net/npm/cocoda-sdk@2/dist/cocoda-sdk.js>
 
 [![](https://data.jsdelivr.com/v1/package/npm/cocoda-sdk/badge?style=rounded)](https://www.jsdelivr.com/package/npm/cocoda-sdk)
 
@@ -55,36 +54,12 @@ Since cocoda-sdk is an ES module, we'll use the `import`/`export` syntax in the
 cocoda-sdk also exports some other members:
 - `CocodaSDK` - the class that is behind the default instance
 - `errors` - see [Errors](#errors)
+- `providers` - an object with all provider classes
 - All individual provider classes - see [Providers](#providers)
   - Note: You need to append `Provider` to the names, e.g. `LocalMappings` is exported as `LocalMappingsProvider`.
 - `addAllProviders` - a method that adds all avaiable providers to an instance
   - Can be called without parameters to add to the default instance. Useful if you need all providers.
 
-### v1 Compatibility
-cocoda-sdk v2 changed how it is exported and therefore it needs to be included differently.
-
-```js
-// CommonJS
-// Previously: const cdk = require("cocoda-sdk")
-// Now:
-const { cdk } = require("cocoda-sdk")
-// or: const cdk = require("cocoda-sdk").cdk
-```
-
-```js
-// ES6
-// Previously: import * as cdk from "cocoda-sdk"
-// Now:
-import { cdk } from "cocoda-sdk"
-```
-
-```js
-// Browser
-// Previously the default instance was globally available under `cdk`.
-// Now the module is available under `CDK` with `cdk` as one of its members. To easily make previous code compatible:
-const { cdk } = CDK
-```
-
 ### Configuration
 cocoda-sdk can be configured after import:
 
@@ -115,6 +90,15 @@ A registry is an individual source of data, for instance a set of concept scheme
 }
 ```
 
+For most providers the configuration should use the BARTOC vocabulary API type URI instead:
+
+```json
+{
+  "api": "http://bartoc.org/api-type/skosmos",
+  "endpoint": "https://www.loterre.fr/skosmos/905/"
+}
+```
+
 A list of available providers can be found [below](#providers). Most providers need additional properties to work correctly.
 
 #### Endpoint Determination
@@ -142,6 +126,17 @@ const registry = cdk.initializeRegistry({
 registry.getMappings()
 ```
 
+Most Providers can also be initialized with API Type URI from [BARTOC vocabulary API types list](https://bartoc.org/en/node/20002):
+
+```js
+const registry = cdk.initializeRegistry({
+  api: "http://bartoc.org/api-type/skosmos",
+  endpoint: "https://www.loterre.fr/skosmos/905/"
+})
+```
+
+It's also possible to directly use Registry classes.
+
 #### Using Registries From a Configuration
 
 If you initialize cocoda-sdk with a [configuration](#configuration), it will initialize all included registries automatically. Those registries are then accessible via `cdk.config.registries`. Alternatively, you can retrieve registries by URI:
@@ -157,12 +152,13 @@ Providers allow access to different types of APIs.
 
 The following providers are offered in cocoda-sdk by default:
 - `Base` - the base provider that all other providers have to inherit from
-- `ConceptApi` - access to concept schemes and concepts via [jskos-server]
+- `ConceptApi` - access to concept schemes and concepts via JSKOS API ([jskos-server] and compatible implementations)
 - `MappingsApi` - access to concordances, mappings, and annotations via [jskos-server]
 
 The following providers are also exported, but have to be added via `cdk.addProvider`:
 - `LocalMappings` - access to local mappings via [localForage](https://github.com/localForage/localForage) (only available in browser)
 - `SkosmosApi` - access to concept schemes and concepts via a [Skosmos](https://github.com/NatLibFi/Skosmos) API
+- `OlsApi`- access to ontologies via Ontology Lookup Service (OLS) API Version 2 (experimental)
 - `LocApi` - access to concept schemes and concepts via the [Library of Congress Linked Data Service](https://id.loc.gov/)
   - **This integration is currently experimental and only supports LCSH and LCNAF.**
 - `Skohub` - access to concept schemes and concepts via a [SkoHub Vocabs](https://blog.lobid.org/2019/09/27/presenting-skohub-vocabs.html)
@@ -174,6 +170,7 @@ The following providers are also exported, but have to be added via `cdk.addProv
 - `ReconciliationApi` - access to mapping suggestions via a [Reconciliation Service API](https://reconciliation-api.github.io/specs/draft/)
 - `OccurrencesApi` - access to concept occurrences via [occurrences-api](https://github.com/gbv/occurrences-api) (will be changed to [occurrences-server](https://github.com/gbv/occurrences-server) in the future)
 - `LabelSearchSuggestion` - access to mapping suggestions using other registries' search endpoints (using [jskos-server])
+- `ModApi` - (experimental) access to concept schemes and concepts via a [MOD](https://github.com/FAIR-IMPACT/MOD) API
 
 To add a provider, append `Provider` to its name and import it together with `cdk`:
 
@@ -186,14 +183,28 @@ Note that in the browser bundle, all providers listed above are included and do
 
 Please refer to each provider's documentation for how exactly to configure that provider: [Documentation](https://gbv.github.io/cocoda-sdk/)
 
+#### Custom providers
+
 It is also possible to add custom providers that inherit from BaseProvider:
 
 ```js
-import CustomProvider from "./custom-provider.js"
+import { cdk, BaseProvider } from "cocoda-sdk"
+
+export class CustomProvider extends BaseProvider {
+  static providerName = "Dummy" 
+  // static providerType = "..."    // Optional URI from https://bartoc.org/api-type/
+
+  getConcepts() {
+    return [
+      { prefLabel: { en: "Hello!" } },
+    ]
+  }
+}
+
 cdk.addProvider(CustomProvider)
 ```
 
-It is then possible to use that provider via cocoda-sdk as well. (See also: Example under [`examples/custom-provider.js`](https://github.com/gbv/cocoda-sdk/blob/master/examples/custom-provider.js).)
+See [`examples/custom-provider.js`](https://github.com/gbv/cocoda-sdk/blob/main/examples/custom-provider.js) for an extended example.
 
 ### Multiple Instances
 
@@ -288,156 +299,161 @@ You can find more in-depth examples here:
 - The [Vuex store module for authentication in Cocoda](https://github.com/gbv/cocoda/blob/dev/src/store/modules/auth.js).
   - Even if you're not using Vue.js, this can be helpful.
   - Cocoda is using cocoda-sdk extensively, so other parts of the code might also be helpful. It has gotten pretty big and complex though.
-- The [API page of Login Server](https://github.com/gbv/login-server/blob/master/views/api.ejs). This is merely an example on how to use `login-client`.
+- The [API page of Login Server](https://github.com/gbv/login-server/blob/main/views/api.ejs). This is merely an example on how to use `login-client`.
 
-## Methods
+## API
 
 A cocoda-sdk instance itself offers only a handful of methods. The actual access to APIs happens through [registries](#registries). The following list of methods assume either an instance of cocoda-sdk (`cdk.someMethod`) or an initialized registry (`registry.someMethod`). Documentation for registry methods is on a per-provider basis. While the API should be the same for a particular methods across providers, the details on how to use it might differ.
 
-### Methods for cocoda-sdk instance
-Please refer to the [documentation](https://gbv.github.io/cocoda-sdk/CocodaSDK.html).
+Please refer to the [documentation](https://gbv.github.io/cocoda-sdk/CocodaSDK.html) for a list of methods of for cocoda-sdk instances.
 
-### Registry Methods - General
+### General
 
-#### `registry.init`
-- [BaseProvider - init](https://gbv.github.io/cocoda-sdk/BaseProvider.html#init)
+- [init](https://gbv.github.io/cocoda-sdk/BaseProvider.html#init)
 
-#### `registry.isAuthorizedFor`
-- [BaseProvider - isAuthorizedFor](https://gbv.github.io/cocoda-sdk/BaseProvider.html#isAuthorizedFor)
+- [isAuthorizedFor](https://gbv.github.io/cocoda-sdk/BaseProvider.html#isAuthorizedFor)
 
-#### `registry.supportsScheme`
-- [BaseProvider - supportsScheme](https://gbv.github.io/cocoda-sdk/BaseProvider.html#supportsScheme)
-- [LabelSearchSuggestionProvider - supportsScheme](https://gbv.github.io/cocoda-sdk/LabelSearchSuggestionProvider.html#supportsScheme)
+- `supportsScheme`. Implemented by:
+  - [BaseProvider](https://gbv.github.io/cocoda-sdk/BaseProvider.html#supportsScheme)
+  - [LabelSearchSuggestionProvider](https://gbv.github.io/cocoda-sdk/LabelSearchSuggestionProvider.html#supportsScheme)
 
-#### `registry.setAuth`
-- [BaseProvider - setAuth](https://gbv.github.io/cocoda-sdk/BaseProvider.html#setAuth)
+- `setAuth`
+  - Implemented by [BaseProvider](https://gbv.github.io/cocoda-sdk/BaseProvider.html#setAuth)
 
-#### `registry.setRetryConfig`
-- [BaseProvider - setRetryConfig](https://gbv.github.io/cocoda-sdk/BaseProvider.html#setRetryConfig)
+- setRetryConfig
+  - Implemented by [BaseProvider](https://gbv.github.io/cocoda-sdk/BaseProvider.html#setRetryConfig)
 
-#### `registry.getCancelTokenSource`
-- [BaseProvider - getCancelTokenSource](https://gbv.github.io/cocoda-sdk/BaseProvider.html#getCancelTokenSource)
+- getCancelTokenSource
 
-### Registry Methods - Concept Schemes
+  - Implemented by [BaseProvider](https://gbv.github.io/cocoda-sdk/BaseProvider.html#getCancelTokenSource)
 
-#### `registry.getSchemes`
-- [ConceptApiProvider - getSchemes](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#getSchemes)
-- [SkosmosApiProvider - getSchemes](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#getSchemes)
+### Concept Schemes
 
-#### `registry.vocSearch`
-- [ConceptApiProvider - vocSearch](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#vocSearch)
+- `getSchemes`    
+    - [ConceptApiProvider](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#getSchemes)
+    - [SkosmosApiProvider](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#getSchemes)
+    - ...
 
-#### `registry.vocSuggest`
-- [ConceptApiProvider - vocSuggest](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#vocSuggest)
+- `vocSearch`
+    - [ConceptApiProvider](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#vocSearch)
+    - ...
 
-### Registry Methods - Concepts
+- `vocSuggest`
+    - [ConceptApiProvider](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#vocSuggest)
 
-#### `registry.getTop`
+### Concepts
+
+#### getTop
 - [ConceptApiProvider - getTop](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#getTop)
+- ...
 
-#### `registry.getConcepts`
+#### getConcepts
 - [ConceptApiProvider - getConcepts](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#getConcepts)
 - [SkosmosApiProvider - getConcepts](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#getConcepts)
+- ...
 
-#### `registry.getNarrower`
+#### getNarrower
 - [ConceptApiProvider - getNarrower](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#getNarrower)
 - [SkosmosApiProvider - getNarrower](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#getNarrower)
+- ...
 
-#### `registry.getAncestors`
+#### getAncestors
 - [ConceptApiProvider - getAncestors](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#getAncestors)
 - [SkosmosApiProvider - getAncestors](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#getAncestors)
+- ...
 
-#### `registry.search`
+#### search
 - [ConceptApiProvider - search](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#search)
 - [SkosmosApiProvider - search](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#search)
+- ...
 
-#### `registry.suggest`
+#### suggest
 - [ConceptApiProvider - suggest](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#suggest)
 - [SkosmosApiProvider - suggest](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#suggest)
+- ...
 
-### Registry Methods - Concordances
+### Concordances
 
-#### `registry.getConcordances`
+#### getConcordances
 - [MappingsApiProvider - getConcordances](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#getConcordances)
+- ...
 
-#### `registry.postConcordance`
+#### postConcordance
 - [MappingsApiProvider - postConcordance](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#postConcordance)
+- ...
 
-#### `registry.putConcordance`
+#### putConcordance
 - [MappingsApiProvider - putConcordance](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#putConcordance)
+- ...
 
-#### `registry.patchConcordance`
+#### patchConcordance
 - [MappingsApiProvider - patchConcordance](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#patchConcordance)
+- ...
 
-#### `registry.deleteConcordance`
+#### deleteConcordance
 - [MappingsApiProvider - deleteConcordance](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#deleteConcordance)
+- ...
 
-### Registry Methods - Mappings
+### Mappings
 
-#### `registry.getMappings`
+#### getMappings
 - [MappingsApiProvider - getMappings](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#getMappings)
 - [LocalMappingsProvider - getMappings](https://gbv.github.io/cocoda-sdk/LocalMappingsProvider.html#getMappings)
 - [ReconciliationApiProvider - getMappings](https://gbv.github.io/cocoda-sdk/ReconciliationApiProvider.html#getMappings)
 - [LabelSearchSuggestionProvider - getMappings](https://gbv.github.io/cocoda-sdk/LabelSearchSuggestionProvider.html#getMappings)
 - [OccurrencesApiProvider - getMappings](https://gbv.github.io/cocoda-sdk/OccurrencesApiProvider.html#getMappings)
 
-#### `registry.getMapping`
+#### getMapping
 - [MappingsApiProvider - getMapping](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#getMapping)
 - [LocalMappingsProvider - getMapping](https://gbv.github.io/cocoda-sdk/LocalMappingsProvider.html#getMapping)
 
-#### `registry.postMapping`
+#### postMapping
 - [MappingsApiProvider - postMapping](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#postMapping)
 - [LocalMappingsProvider - postMapping](https://gbv.github.io/cocoda-sdk/LocalMappingsProvider.html#postMapping)
 
-#### `registry.postMappings`
+#### postMappings
 - [BaseProvider - postMappings](https://gbv.github.io/cocoda-sdk/BaseProvider.html#postMappings)
 
-#### `registry.putMapping`
+#### putMapping
 - [MappingsApiProvider - putMapping](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#putMapping)
 - [LocalMappingsProvider - putMapping](https://gbv.github.io/cocoda-sdk/LocalMappingsProvider.html#putMapping)
 
-#### `registry.patchMapping`
+#### patchMapping
 - [MappingsApiProvider - patchMapping](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#patchMapping)
 - [LocalMappingsProvider - patchMapping](https://gbv.github.io/cocoda-sdk/LocalMappingsProvider.html#patchMapping)
 
-#### `registry.deleteMapping`
+#### deleteMapping
 - [MappingsApiProvider - deleteMapping](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#deleteMapping)
 - [LocalMappingsProvider - deleteMapping](https://gbv.github.io/cocoda-sdk/LocalMappingsProvider.html#deleteMapping)
 
-#### `registry.deleteMappings`
+#### deleteMappings
 - [BaseProvider - deleteMappings](https://gbv.github.io/cocoda-sdk/BaseProvider.html#deleteMappings)
 
-### Registry Methods - Annotations
-
-#### `registry.getAnnotations`
-- [MappingsApiProvider - getAnnotations](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#getAnnotations)
-
-#### `registry.postAnnotation`
-- [MappingsApiProvider - postAnnotation](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#postAnnotation)
+### Annotations
 
-#### `registry.putAnnotation`
-- [MappingsApiProvider - putAnnotation](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#putAnnotation)
+- [getAnnotations](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#getAnnotations)
+- [postAnnotation](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#postAnnotation)
+- [putAnnotation](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#putAnnotation)
+- [patchAnnotation](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#patchAnnotation)
+- [deleteAnnotation](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#deleteAnnotation)
 
-#### `registry.patchAnnotation`
-- [MappingsApiProvider - patchAnnotation](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#patchAnnotation)
+### Occurrences
 
-#### `registry.deleteAnnotation`
-- [MappingsApiProvider - deleteAnnotation](https://gbv.github.io/cocoda-sdk/MappingsApiProvider.html#deleteAnnotation)
+- [getOccurrences](https://gbv.github.io/cocoda-sdk/OccurrencesApiProvider.html#getOccurrences)
 
-### Registry Methods - Various
+### Types
 
-#### `registry.getOccurrences`
-- [OccurrencesApiProvider - getOccurrences](https://gbv.github.io/cocoda-sdk/OccurrencesApiProvider.html#getOccurrences)
+`getTypes({ scheme })` returns a list of [types](https://gbv.github.io/jskos/#resource-and-property-types) for some concept scheme(s). Implemented by:
 
-#### `registry.getTypes`
-- [ConceptApiProvider - getTypes](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#getTypes)
-- [SkosmosApiProvider - getTypes](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#getTypes)
+- [ConceptApiProvider](https://gbv.github.io/cocoda-sdk/ConceptApiProvider.html#getTypes)
+- [SkosmosApiProvider](https://gbv.github.io/cocoda-sdk/SkosmosApiProvider.html#getTypes)
+- [OlsApiProvider](https://gbv.github.io/cocoda-sdk/OlsApiProvider.html#getTypes)
+- [LobidApiProvider](https://gbv.github.io/cocoda-sdk/LobidApiProvider.html#getTypes)
 
-## Errors
-cocoda-sdk defines some custom errors.
+### Errors
+cocoda-sdk defines some custom errors, grouped in exporteable object `errors`:
 
 ```js
-const { errors } = require("cocoda-sdk") // CommonJS
 import { errors } from "cocoda-sdk"
 ```
 
@@ -454,37 +470,13 @@ The following errors are defined:
 For details about the errors, refer to the [documentation](https://gbv.github.io/cocoda-sdk/index.html).
 
 ## Maintainers
-- [@stefandesu](https://github.com/stefandesu)
 - [@nichtich](https://github.com/nichtich)
 
-## Publish
-Please work on the `dev` branch during development (or better yet, develop in a feature branch and merge into `dev` when ready).
-
-When a new release is ready (i.e. the features are finished, merged into `dev`, and all tests succeed), run the included release script (replace "patch" with "minor" or "major" if necessary):
-
-```bash
-npm run release:patch
-```
-
-This will:
-- Run tests and build to make sure everything works
-- Switch to `dev`
-- Make sure `dev` is up-to-date
-- Run `npm version patch` (or "minor"/"major")
-- Push changes to `dev`
-- Switch to `master`
-- Merge changes from `dev`
-- Push `master` with tags
-- Switch back to `dev`
-
-After running this, GitHub Actions will automatically publish the new version to npm. It will also create a new GitHub Release draft. Please edit and publish the release manually.
-
-## Contribute
-PRs accepted.
+## Contributing
 
-Small note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+See [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
-MIT Copyright (c) 2021 Verbundzentrale des GBV (VZG)
+MIT Copyright (c) 2021- Verbundzentrale des GBV (VZG)
 
 [jskos-server]: https://github.com/gbv/jskos-server