Introduction

The Python client, as all other implementations, for the PineXQ follows the principle of a task based hypermedia API, where there is no fixed structure of endpoints and tasks (think commands with parameters) are used to modify resources. Instead ,the server presents you at each “endpoint” with options where to navigate next. Imagine it similar to navigating HTML pages, where links provide you the paths to the next pages. In fact, the client is based on HTTP request, same as browser uses to get HTML pages. With this concept, the client doesn’t need to be rebuilt every time something changes on the server side, but it just works with the structure given by the server. This allows us to build the client from a few simple building blocks and then explore the API using them. For deeper understanding we recommend that you read the Siren Hypermedia Specification.

To provide a layer of convenience this Python client implements typed objects on-top of the Siren primitives. Those represent all possible resources you may encounter navigating the API and allow for auto-completion and type-safety during development and model validation at runtime.

Below we will briefly introduce the Siren primitives first before describing PineXQ-specific parts.

Siren building blocks

The Python client wraps the basic building blocks on classes providing convenience functions to navigate the API and having always a type save representation of the current resource.

Entity

A HypermediaClientObject (Hco) wraps an entity and offers all actions and link available for the current resource in the current state. Additionally, most resources have properties like their name, version and so on, which are mapped to properties of the Hco class itself. These are usually simple data types (like str, int, …) or Enums encapsulating specific sets of possible values.

Embedded entities live inside host entities e.g. a QueryResult contains several result entities.

Link

Links encapsulate a URI representing an internal resource; they are also used as IDs since they uniquely identify a resource. Calling the .navigate() function on an internal resource follows the link and resolves it directly, returning the specific Hco class of the target entity.

External links offer a .download() method, doing an HTTP request and returning the downloaded data.

Action

All Actions offer a .execute() method to perform it on the corresponding entity. Some action require parameters that have to be provided to the execute-method in an action-specific parameter object.