@dasch-swiss/dsp-js
v10.2.2
Published
JavaScript library that handles API requests to Knora
Downloads
3,419
Readme
DSP-JS-LIB — A library to easily connect to DSP-API (Knora)
Introduction
Purpose of DSP-JS-LIB
The purpose of DSP-JS-LIB is to facilitate the communication with DSP-API in web clients developed with TypeScript/JavaScript. DSP-JS-LIB depends on RxJS and is web framework agnostic (it can be used with Angular, React, Vue.js etc.).
DSP-JS-LIB offers the following features:
- handling of HTTP calls to connect to DSP-API
- (de)serialisation from and to JSON-LD so the web client can work with classes instead
- methods that combine different HTTP calls to DSP-API into one method call
- caching for different types of data so fewer HTTP calls to DSP-API have to be performed
Basic Structure of DSP-JS-LIB
DSP-JS-LIB's architecture is based on endpoints that correspond to DSP-API's endpoints.
The following main endpoints are available through DSP-JS-LIB:
- admin (
AdminEndpoint
): getting and modifying users, projects, permissions etc. - v2 (
V2Endpoint
): requesting and modifying resources and values using DSP-API version 2. - system (
SystemEndpoint
): DSP-API's health status.
Each of these main endpoints offers endpoints for specific operations.
Admin
- admin.usersEndpoint (
UsersEndpointAdmin
): offers methods to administer users. - admin.groupsEndpoint (
GroupsEndpointAdmin
): offers methods to administer groups. - admin.projectsEndpoint (
ProjectsEndpointAdmin
): offers methods to administer projects. - admin.permissionsEndpoint (
PermissionsEndpointAdmin
): offers methods to administer permissions. - admin.listsEndpoint (
ListsEndpointAdmin
): offers methods to administer lists.
V2
- v2.auth (
AuthenticationEndpointV2
): offers methods to authenticate. - v2.onto (
OntologiesEndpointV2
): offers methods to get ontology information. - v2.res (
ResourcesEndpointV2
): offers methods to work with resources. - v2.values (
ValuesEndpointV2
): offers methods to work with values. - v2.list (
ListsEndpointV2
): offers methods to retrieve list nodes and lists. - v2.search (
SearchEndpointV2
): offers methods to search. - v2.metadata (
ProjectMetadataEndpointV2
): offers methods to work with project metadata.
System
- system.healthEndpoint (
HealthEndpointSystem
): offers methods to get DSP-API's status.
Consult the API docs for more details about the available endpoints. For each main endpoint, you'll find a category in the API docs:
- admin:
Endpoint Admin Classes
- v2:
Endpoint V2 Classes
- system:
Endpoint System Classes
You can also use the full text search to search for an endpoint's class name within the API docs, e.g., ResourcesEndpointV2
.
See section Getting started for more usage information.
See design documentation for a detailed description of DSP-JS-LIB's design and architecture.
RxJS Observables
DSP-JS-LIB's endpoints return observables to the client.
An Observable
represents the result of an asynchronous request to DSP-API that will either succeed or fail.
An Observable
is an RxJS construct that the client can subscribe to.
Getting started
Install DSP-JS-LIB
Run npm install @dasch-swiss/dsp-js --save
to install DSP-JS-LIB in your npm project.
Dependencies and Peer Dependencies
DSP-JS-LIB depends on jsonld and json2typescript.
These dependencies will be installed when you run npm install
in your project.
RxJS is a peer dependency of this library and is not installed when running npm install
.
Note that DSP-JS-LIB requires major version 6 of rxjs
.
Make sure that the framework you are using, e.g., Angular, requires major version 6 of RxJS to ensure the peer dependency will be met.
Otherwise, install it with npm install [email protected] --save
.
Start Using DSP-JS-LIB
In order to get started using DSP-JS-LIB, you have to create a KnoraApiConfig
instance and pass it to KnoraApiConnection
's constructor:
// import from DSP-JS-LIB
import { KnoraApiConfig, KnoraApiConnection } from "@dasch-swiss/dsp-js";
// create the configuration
const config: KnoraApiConfig = new KnoraApiConfig("https", "api.dasch.swiss");
// create a connection instance
const knoraApiConnection: KnoraApiConnection = new KnoraApiConnection(config);
Once you have set up the connection instance, you can use any of DSP-JS-LIB's endpoints to perform requests to DSP-API:
// formal example
knoraApiConnection.[mainEndpoint].[endpoint].[method(...)]
// admin users endpoint example, see UsersEndpointAdmin in API docs
knoraApiConnection.admin.usersEndpoint.getUserByIri("userIri").subscribe(...);
// v2 search endpoint example, see SearchEndpointV2 in API docs
knoraApiConnection.v2.search.doFulltextSearch("searchLabel").subscribe(...);
// system health endpoint example, see HealthEndpointSystem in API docs
knoraApiConnection.system.getHealthStatus().subscribe(...);
In the following full example, we are requesting a resource from DSP-API:
// request a resource using the resources endpoint from v2
knoraApiConnection.v2.res.getResource(iri).subscribe(
(resource: ReadResource) => {
// "resource" represents a resource retrieved from DSP-API
console.log(res);
},
(error) => {
// if, for some reason, the request failed
console.error(error);
}
);
For more information about available endpoints and methods, consult the API docs.
Release Notes
For the release notes see GitHub releases.