DSpace.API (dspace_ex v0.1.0-alpha2)

Copy Markdown View Source

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 DSpace.API.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:

{: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. 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 :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.

Summary

Types

t()

A DSpace API client structure.

Functions

authenticated?(api)

Verifies if the passed client is authenticated with the DSpace API.

login(api, username, password)

Authenticates with a DSpace API and returns an updated client structure.

login!(api, username, password)

Authenticates the client with a DSpace API and raises on errors.

new(attributes)

Creates a new API client.

put_access_token(api, access_token)

Updates the Access token.

put_api_version(api, version)

Updates the API version.

put_csrf_token(api, csrf_token)

Updates the CSRF token.

put_endpoint(api, endpoint)

Updates the API endpoint.

put_http_impl(api, http_impl)

Updates the HTTP adapter implementation.

put_on_response_hook(api, on_response_hook)

Updates the session hook function.

put_user_agent(api, user_agent)

Updates the user agent.

request(operation, api, options \\ [])

Makes a request to the API and returns a result or an error.

request!(operation, api, options \\ [])

Makes a request to the API and returns a result or raises an error.

stream!(operation, api, options \\ [])

Makes a request to the API and returns a stream.

Types

t()

@type t() :: %DSpace.API{
  access_token: nil | binary(),
  api_version: binary(),
  csrf_token: nil | binary(),
  endpoint: URI.t() | binary() | (-> term()),
  http_impl: {module(), keyword()},
  on_response_hook: nil | (map() -> :ok),
  user_agent: binary()
}

A DSpace API client structure.

Functions

authenticated?(api)

@spec authenticated?(t()) :: boolean()

Verifies if the passed client is authenticated with the DSpace API.

Returns false if the server indicates the client is not authenticated, or if the server is unreachable. Callers who want to separate transport errors from authentication status should request DSpace.API.Auth.status/0 directly.

Parameters

login(api, username, password)

@spec login(t(), username, password) :: {:ok, t()} | {:error, Exception.t()}
when username: binary(), password: binary()

Authenticates with a DSpace API and returns an updated client structure.

Returns returns a DSpace.API.t/0 client structure with updated access- and CSRF tokens. Managing token lifecycle (checking expiry, deciding when to refresh) is the responsibility of the consuming application. The token is a JWT and contains an exp claim. See DSpace.API.Auth.refresh_access_token/0.

Executing this operation will fetch a CSRF token from the API first if none is configured in the client struct, since that is a prerequisite for hitting the login endpoint.

Parameters

  • api - A DSpace.API.t/0 structure
  • username - Username as a string
  • password - Password as a string

Usage

The login operation is executed directly when calling this function. The returned client can then immediately be used for follow-up operations:

client =
  [endpoint: "https://example.com/server"]
  |> DSpace.API.new()
  |> DSpace.API.login("username", "password")

items =
  Item.list()
  |> DSpace.API.stream!(client)

login!(api, username, password)

@spec login!(t(), username, password) :: t()
when username: binary(), password: binary()

Authenticates the client with a DSpace API and raises on errors.

Similar to login/3, but returns the updated client structure directly or raises on errors.

new(attributes)

@spec new(attributes :: keyword()) :: t()
@spec new(endpoint :: URI.t() | binary() | fun()) :: t()

Creates a new API client.

Parameters

This function takes either

  • a keyword list of attributes or
  • a single argument that represents the DSpace REST endpoint; either as
    • an URI.t/0 structure
    • a string
    • a 0-arity function that returns a URI.t/0 structure or a string

Attributes

  • endpoint - The DSpace REST endpoint, e.g. https://example.com/server. Can be either
    • an URI.t/0 structure
    • a string
    • a 0-arity function that returns a URI.t/0 structure or a string
  • :access_token - Optional login token or API key used for authentication
  • :csrf_token - Optional CSRF token. Needed for all modifying requests
  • :api_version - Optional DSpace API version as a string, defaults to 9.2.0
  • :user_agent - Optional User agent string, defaults to dspace-ex/0.1.0-alpha2
  • :http_impl - Optional HTTP adapter implementation and options as {module, options}
  • :on_response_hook - Optional callback function invoked when CSRF tokens are updated

put_access_token(api, access_token)

@spec put_access_token(t(), access_token :: binary()) :: t()

Updates the Access token.

Parameters

  • api - A DSpace.API.t/0 structure
  • access_token - Login token or API key as a string

put_api_version(api, version)

@spec put_api_version(t(), version :: binary()) :: t()

Updates the API version.

Parameters

  • api - A DSpace.API.t/0 structure
  • version - DSpace API version as a string

put_csrf_token(api, csrf_token)

@spec put_csrf_token(t(), csrf_token :: binary()) :: t()

Updates the CSRF token.

Parameters

put_endpoint(api, endpoint)

@spec put_endpoint(t(), endpoint :: URI.t() | binary()) :: t()

Updates the API endpoint.

Parameters

put_http_impl(api, http_impl)

@spec put_http_impl(t(), adapter :: {module(), keyword()}) :: t()

Updates the HTTP adapter implementation.

Parameters

put_on_response_hook(api, on_response_hook)

@spec put_on_response_hook(t(), (map() -> :ok) | nil) :: t()

Updates the session hook function.

Parameters

  • api - A DSpace.API.t/0 structure
  • on_response_hook - A 1-arity function invoked when CSRF tokens are updated

put_user_agent(api, user_agent)

@spec put_user_agent(t(), user_agent :: binary()) :: t()

Updates the user agent.

Parameters

request(operation, api, options \\ [])

@spec request(DSpace.API.Operation.t(), t(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}

Makes a request to the API and returns a result or an error.

Parameters

Options

  • :transform - Whether to transform the response. If set to false, returns a DSpace.API.HTTP.Response.t/0 structure (defaults to true)
  • request option overrides passed to the HTTP adapter

request!(operation, api, options \\ [])

@spec request!(DSpace.API.Operation.t(), t(), keyword()) :: term()

Makes a request to the API and returns a result or raises an error.

For parameters and options, see request/3.

stream!(operation, api, options \\ [])

@spec stream!(DSpace.API.Operation.t(), t(), keyword()) :: Enumerable.t()

Makes a request to the API and returns a stream.

For parameters and options, see request/3.