.. _reference:

Reference
=========

.. _example-edg-server-configuration:

Example EDG server configuration
--------------------------------

The client and GraphQL examples assume the EDG server:

* is running at ``http://localhost:8080``
* supports basic authentication
* has administrator credentials ``Admin_user/password32``

The ``edg-samples`` Docker images satisfy the requirements.

The GraphQL examples further assume that the EDG-Samples projects have been installed. The ``edg-samples`` Docker images also satisfy this requirement.


.. _lib-java-apidocs:

Client library reference
------------------------

* `Java <_static/lib-java-apidocs/index.html>`_


.. _maven-artifacts:

Maven artifacts
---------------

The TopQuadrant Nexus repository includes Maven artifacts for the EDG client Java library.

See `this document <https://docs.google.com/document/d/1ywq4yHEx1xwbi6nPZJ0KMXhWuRWknBEFKO350sRMybc/edit?usp=sharing>`_ for instructions on how to set up access.

Releasing Maven artifacts
+++++++++++++++++++++++++

The process for releasing new Java artifacts to the Maven repository is:

#. Checkout ``main`` branch.
#. Manually change any Scala ``build.sbt`` dependencies on this project to the next release version.
#. Commit those changes but don't push.
#. Call ``lib/java/script/prepare-release.sh`` to run Maven ``release:prepare``. Tag with the new version number without any prefixes or suffixes e.g., ``1.0.0``. The prepare process tags the current ```X.X.X-SNAPSHOT`` as ``X.X.X`` and advances pom.xml's to the next ``-SNAPSHOT``.
#. Push changes.
#. Manually change any Scala ``build.sbt`` dependencies on this project to the next ``SNAPSHOT`` version.
#. Commit those changes and push.
#. Run `git clean -f` to delete detritus created by Maven `release:prepare`. We don't use `release:perform` because CI pushes the release to Nexus.

.. _configuration-properties:

Configuration properties
------------------------

The EDG client libraries can be configured from various configuration sources that support a property-value interface, such as:

* -D system properties (Java only)
* environment variables

Additional property-value sources such as Java servlet contexts can be added in a language-specific setting.

The system property keys are listed below. They start with the prefix ``edg.client.``. Equivalent environment variables are in parentheses. Environment variables start with the prefix ``EDG_CLIENT_`` and are all uppercase.

**edg.client.authenticationMethod (EDG_CLIENT_AUTHENTICATIONMETHOD)**

Method for the client to use to authenticate with the server. The value must be one of ``BASIC``, ``FORM``, ``NOP``, or ``OAUTH``.

The value of ``edg.client.authenticationMethod`` implies that other values must be specified. For example, if the ``edg.client.authenticationMethod`` is ``BASIC`` or ``FORM``, then ``edg.client.username`` and ``edg.client.password`` must be specified.

If ``edg.client.authenticationMethod`` is not specified, then it is inferred from other properties. For example, if ``edg.client.username`` and ``edg.client.password`` are specified but ``edg.client.authenticationMethod`` is not, then the latter defaults to ``BASIC``.

**edg.client.bearerToken (EDG_CLIENT_BEARERTOKEN)**

Bearer token to use to authenticate with the EDG server. This is normally a long hexadecimal string obtained from an OAuth identity provider.

**edg.client.oauthClientId (EDG_CLIENT_OAUTHCLIENTID), edg.client.oauthClientSecret (EDG_CLIENT_OAUTHCLIENTSECRET), edg.client.oauthTokenEndpointUrl (EDG_CLIENT_OAUTHTOKENENDPOINTURL)**

Credentials to obtain an `OAuth <https://en.wikipedia.org/wiki/OAuth>`_ access token using the client credentials flow. The client will authenticate API requests by attaching the access token to them in a ``Bearer`` header.

All three properties must be specified for ``OAUTH`` authentication.

See the `TopBraid EDG Administration Guide <https://doc.topquadrant.com/7.0/server-installation/#OAuth_Authentication>`_ for information on setting up OAuth with TopBraid EDG.

**edg.client.password (EDG_CLIENT_PASSWORD)**

Password to use to authenticate with the EDG server, such as ``password32``. This is required for ``BASIC`` or ``FORM`` authentication.

**edg.client.serverBaseUrl (EDG_CLIENT_SERVERBASEURL)**

The absolute URL of the EDG server, such as ``http://your-edg-server.example.com/edg/`` or ``http://localhost:8080/``. The client builds on this URL to access the EDG API. For example, with an EDG base URL of ``http://localhost:8080/`` the server administration page is ``http://localhost:8080/tbl/admin``.

**edg.client.username (EDG_CLIENT_USERNAME)**

Username to use to authenticate with the EDG server, such as ``Admin_username``. This is required for ``BASIC`` or ``FORM`` authentication