4. Explanations

4.1. Java library

4.1.1. Design

Client

The Client interface is the primary entry point of the library. The factory method Client.create constructs instances of the client. Client.create takes a ClientConfiguration with the server URL and credentials for authentication.

Api

The Client interface extends the Api interface by adding some convenience operations. Api reflects low-level server API functions the client knows about. Each of these server API functions is declared as an ApiFunction sub-interface, such as CreateProjectApiFunction. Every ApiFunction sub-interface has a single method, which mirrors the underlying server API. The Api interface is the union of these ApiFunction sub-interfaces.

The API design errs on the side of reflecting what the server accepts rather than on the side of consistency. This is especially visible in API function parameter names, which are inconsistent between functions. One-to-one mapping between client and server at the lowest level makes it simpler to debug the client and analyze what the server is doing. The intention is for API to be a lowest-common-denominator base for more consistent layers above it that exploit JVM-based language idioms.

4.1.2. Implementation

The default Client implementation delegates its work to various implementation classes, which implement subsets of the known ApiFunctions corresponding to how they are implemented in (and called on) the server. For example, createProject is implemented in SWP on the server, so it is implemented in SwpClient in the client. Grouping client functions in this way encourages code reuse, since the HTTP requests are similar for e.g., all SWP requests.

4.1.3. Java development practices

The library strives to make use of Java best practices:

• Avoiding null and using java.util.Optional

• Guava immutable collections

• Immutable data classes

• Preconditions

• Design patterns such as the facade pattern in Client or parameter objects

• Java 8 streams

• Standardized scripts for building the code and executing tests (Scripts to Rule Them All)

• Aggressive use of the final keyword

• SOLID principles such as “depend upon abstractions, not concretions”

• Tiny types

• Cleanly separating the API definition from its implementation

• Consistent naming

• Consistent syntax, enforced by automatic formatting

4.2. Python library

4.2.1. Design

The design of the Python library is adapted from that of the Java library: a Client entrypoint, immutable ClientConfiguration and associated data classes, and so on.

The Python library has relatively few dependencies, by design:

• The de facto standard rdflib and SPARQLWrapper libraries for working with RDF and remote SPARQL endpoints, respectively

• The simple GraphQL client sgqlc, which is also used by the GraphQL framework to generate client-side Python for EDG GraphQL endpoints

The EDG client Python library delegates to the HTTP client in the Python standard library urllib. Both SPARQLWrapper and sgqlc also delegate to urllib.