RKorAPClient (version 1.0.0)

KorAPConnection-class: Class KorAPConnection

Description

KorAPConnection objects represent the connection to a KorAP server. New KorAPConnection objects can be created by new("KorAPConnection").

Usage

# S4 method for KorAPConnection
initialize(
  .Object,
  KorAPUrl = "https://korap.ids-mannheim.de/",
  apiVersion = "v1.0",
  apiUrl,
  accessToken = getAccessToken(KorAPUrl),
  oauthClient = NULL,
  oauthScope = "search match_info",
  authorizationSupported = TRUE,
  userAgent = "R-KorAP-Client",
  timeout = 240,
  verbose = FALSE,
  cache = TRUE
)
# S4 method for KorAPConnection
apiCall(
  kco,
  url,
  json = TRUE,
  getHeaders = FALSE,
  cache = kco@cache,
  timeout = kco@timeout
)
# S4 method for KorAPConnection
clearCache(kco)
# S4 method for KorAPConnection
show(object)

Value

KorAPConnection() object that can be used e.g. with corpusQuery()

Arguments

.Object

KorAPConnection object

KorAPUrl

URL of the web user interface of the KorAP server instance you want to access.

apiVersion

which version of KorAP's API you want to connect to.

apiUrl

URL of the KorAP web service.

accessToken

OAuth2 access token. For queries on corpus parts with restricted access (e.g. textual queries on IPR protected data), you need to authorize your application with an access token. You can obtain an access token in the OAuth settings of your KorAP web interface.

More details are explained in the authorization section of the RKorAPClient Readme on GitHub.

To use authorization based on an access token in subsequent queries, initialize your KorAP connection with:

kco <- new("KorAPConnection", accessToken="<access token>")

In order to make the API token persistent for the currently used KorAPUrl (you can have one token per KorAPUrl / KorAP server instance), use:

persistAccessToken(kco)

This will store it in your keyring using the keyring::keyring-package. Subsequent new("KorAPConnection") calls will then automatically retrieve the token from your keying. To stop using a persisted token, call clearAccessToken(kco). Please note that for DeReKo, authorized queries will behave differently inside and outside the IDS, because of the special license situation. This concerns also cached results which do not take into account from where a request was issued. If you experience problems or unexpected results, please try kco <- new("KorAPConnection", cache=FALSE) or use clearCache() to clear the cache completely.

An alternative to using an access token is to use a browser-based oauth2 workflow to obtain an access token. This can be done with the auth() method.

oauthClient

OAuth2 client object.

oauthScope

OAuth2 scope.

authorizationSupported

logical that indicates if authorization is supported/necessary for the current KorAP instance. Automatically set during initialization.

userAgent

user agent string.

timeout

tineout in seconds for API requests (this does not influence server internal timeouts).

verbose

logical that decides whether following operations will default to be verbose.

cache

logical that decides if API calls are cached locally. You can clear the cache with clearCache().

kco

KorAPConnection object

url

request url

json

logical that determines if JSON result is expected

getHeaders

logical that determines if headers and content should be returned (as a list)

object

KorAPConnection object

Slots

KorAPUrl

URL of the web user interface of the KorAP server used in the connection.

apiVersion

requested KorAP API version.

indexRevision

indexRevision code as reported from API via X-Index-Revision HTTP header.

apiUrl

full URL of API including version.

accessToken

OAuth2 access token.

oauthClient

OAuth2 client object.

oauthScope

OAuth2 scope.

authorizationSupported

logical that indicates if authorization is supported/necessary for the current KorAP instance. Automatically set during initialization.

userAgent

user agent string used for connection the API.

timeout

timeout in seconds for API requests (this does not influence server internal timeouts)

verbose

logical that decides whether operations will default to be verbose.

cache

logical that decides if API calls are cached locally.

welcome

list containing HTTP response received from KorAP server welcome function.

Examples

if (FALSE) {

kcon <- new("KorAPConnection", verbose = TRUE)
kq <- corpusQuery(kcon, "Ameisenplage")
kq <- fetchAll(kq)
}

if (FALSE) {

kcon <- new("KorAPConnection", verbose = TRUE, accessToken="e739u6eOzkwADQPdVChxFg")
kq <- corpusQuery(kcon, "Ameisenplage", metadataOnly=FALSE)
kq <- fetchAll(kq)
kq@collectedMatches$snippet
}