Represents a DSpace API client configuration.

Basic Usage / Configuration

dspace_ex doesn't prescribe the configuration strategy of consuming applications. For API interactions, declare a t/0 structure with the necessary configuration when you need it:

client = %DSpace.API{
  endpoint: "https://example.com/server",
  access_token: "my-access-token",
  csrf_token: "my-csrf-token"
}

Then, use the client struct to perform an operation with one of the request functions:

{:ok, item} =
  "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  |> DSpace.API.Item.fetch()
  |> DSpace.API.request(client)

See new/1 for all client configuration options.

Session Management

Per DSpace API contract, all responses need to be monitored for CSRF token updates, regardless of client or use context. In practice, the actual implementation of the DSpace backend does not currently refresh CSRF tokens with every request, only with login/logout, when the token refresh endpoints are called, or the client sends an invalid token.

The optional :on_response_hook field allows applications to handle CSRF token updates. When set, the function will be invoked whenever a response header contains a CSRF token (which should be every response).

client = %DSpace.API{
    endpoint: "https://example.com/server",
    on_response_hook: &MyApp.Session.update_csrf/1
}

The hook will receive a map with a :csrf_token key. Invocation is synchronous and will block until the hook returns. It's probably best to think about using a separate process or a task to invoke the function for asynchronous handling, depending on your session management strategy.

API Compatibility

The DSpace API is not versioned. Some endpoints and behaviours differ across DSpace versions and distributions, including "patch" or "minor" version bumps. Per default, operations in dspace_ex assume the latest DSpace release supported and may not work correctly with instances running older versions of DSpace.

However, dspace_ex includes version-specific overrides where the API differences are known. To enable them, include the DSpace version of the instance you are connecting to in the client struct:

DSpace

client = %DSpace.API{
  endpoint: "https://example.com/server",
  api_version: "7.6.2"
}

CRIS fork

If your connect to an instance running the DSpace-CRIS fork, set the cris_version field instead of api_version in the client struct:

client = %DSpace.API{
  endpoint: "https://example.com/server",
  cris_version: "2023.02.07"
}

If you target a version prior to the 2023.01.01 release, please review the DSpace.API.Version module documentation.

Doing so will

• adjust operation behaviour to the targeted DSpace version
• return a DSpace.API.Operation.Error.t/0 when you try to perform an operation that is not supported on the targeted instance instead of making a request to the server

Configuring version information at runtime

There might be scenarios where the API version of the DSpace instance you are interacting with is not available at compile time of your application. To initialise or update a client configuration from a live API directly, see load_version/1. To source the API version for other configuration strategies, use the operation DSpace.API.Version.fetch/0.