Navigating the API

The API is designed to be navigable and discoverable. Whether using the generic web client (HUI) or Python client, the concept follows the same principles.

You enter the API through the API entry point, e.g. https://myhost.com/api/EntryPoint, which will deliver a document describing where you can go next. This is done by links with attached labels (relations). This is very similar to navigating a web page in a browser, where you click on links and then get presented a new html document.

Therefore, when thinking about the API it is advisable to not think about endpoints, which are embedded in the presented low level documents, but rather about what path to go through the API to reach a certain resource.

Navigating to the Info node

To go to the Info node, we need to enter the API and get the initial Entrypoint; from there, follow the link Info to reach the destination node. Note that the Info node has an embedded entity User. This indicates that a user is embedded in the result with its full data.

This navigation is indicated by the following shorthand:

Entrypoint --Info--> Info

The embedded User is noted like this:

Info --Entity:CurrentUser--o User

Navigation using the Python client

from pinexq.client.job_management import EntryPointHco, enter_jma
# httpx client is already configured with host and credentials
entrypoint: EntryPointHco = enter_jma(client)
info = entrypoint.info_link.navigate()

Through the API

Many things are possible. The HCO objects represent the low-level implementations of the Job, ProcessingStep, and WorkData classes, and much more. While the high-level classes are often more convenient, it is sometimes necessary to access the HCO objects directly. Searching, in particular, is done programmatically this way.