GraphQL

Arkitekt was designed to be open and expandable. Building on the middleman approach, it was an early design decision to establish Arkitekt as a framework, rather than a tool. This entailed for Arkitekt to adapt a developer first or API first approach. In developing this API, it was paramount to adopt open standards that are widely used and that fit well for the Arkitekt paradigm of lab-wide task assignment and scientific data exploration.

Arkitekt therefore exposes all its functionality through a set of GraphQL APIs. GraphQL is an API protocol developed by Facebook to facilitate a one-stop-shop and developer-friendly retrieval and manipulation of data with a high level of relationships, such as their friendship graph. It was designed to overcome issues in other API protocols such as REST, where when trying to explore highly relational data, dedicated and separately orchestrated requests to the backend needed to be performed.

Why we like GraphQL

1. Flexibility: With GraphQL, clients can specify exactly what data they need, reducing over-fetching or under-fetching of data. For bioimage analysis, where datasets can be large and complex, this ensures efficient data retrieval.

2. Strongly Typed: GraphQL is strongly typed. This means that the shape and type of the response are known in advance, which can be particularly useful in bioimage analysis where ensuring data integrity and consistency is crucial. Also it allows you to use the full power of your IDE to explore the API.

3. Evolution of your Schema: As bioimage analysis techniques and tools evolve, the data structure and requirements might change. GraphQL allows for the addition of new fields and types without impacting existing queries, ensuring backward compatibility.

4. Aggregated Data: Often in bioimage analysis, data from multiple sources or related entities need to be fetched. GraphQL allows for fetching data from multiple sources in a single query, simplifying client-side data aggregation. With soon to be implemened federation, you can even fetch data from different Arkitekt services in a single query.

5. Real-time Updates: With subscriptions in GraphQL, clients can be notified in real-time when certain data changes. This can be invaluable in bioimage analysis when monitoring the progress or outcomes of certain analyses (e.g in streaminganalysis)

6. Self-documenting: GraphQL APIs come with introspection capabilities, making it easier for developers to understand the available data, types, queries, and mutations, t hereby fostering faster and more accurate development. Just check the GraphIQL interface of your Arkitekt server.

7. Ecosystem & Tooling: The growing popularity of GraphQL has led to a rich ecosystem of tools, libraries, and client-side frameworks. This can speed up development and offer advanced features for bioimage analysis data servers out of the box. Indeed a lot of the Arkitektl client libraries are build around this ecosystem (e.g. graphql-codegen and turms)

What does this boil down to?

Well GraphQL allows you to declaritively specify what data you want to fetch from the server, and the server will return exactly that data, exploring all the relationships between the data. This is best explained with an example. Lets look at the below query. This query fetches the name of the image, the name of the ROIs, and the shape of the image.

The GraphQL request, resolve, response

React developer? Try it out Here

We can talk ages about the ease of use of graphql. But you can try it out yourself. Here is a simple example of a React component that uses graphql to fetch data from yur local Arkitekt server. You can just change the query to fetch any data you want.

Live Editor

function Display(props) {
  const { data } = useMikroQuery(gql`
    query {
      representations(limit: 3) {
        id
        name
      }
    }
  `);

  return (
    <div className="flex flex-col gap-2">
      {data &&
        data.representations.map((image) => (
          <div className="bg-back-800 px-2">{image.name} </div>
        ))}
    </div>
  );
}

Result

Please connect to your Server first to use this Feature

By changing the query, you can fetch any data you want. For example, here we fetch the name and shape of the image, as well as the labels of the ROIs.

Live Editor

function Display(props) {
  const { data } = useMikroQuery(gql`
    query {
      representations(limit: 3) {
        id
        name
        rois {
          id
          label
        }
        store
        shape
      }
    }
  `);

  return (
    <div className="flex flex-col gap-2">
      {data &&
        data.representations.map((image) => (
          <>
            <div className="bg-back-800 px-2 rounded rounded-md">
              {image.name}{" "}
            </div>
            <div className="bg-green-200">
              {image.rois.map((roi) => (
                <div className="bg-back-800 px-2">{roi.label} </div>
              ))}
            </div>
            <div>
              {image.shape.map((i) => (
                <i>{i} </i>
              ))}
            </div>
          </>
        ))}
    </div>
  );
}

Result

Please connect to your Server first to use this Feature

Python developer? Look here

While we can't provide you with an interactive playground to explore GraphQL just, yet just have a look at the source code of our client apps. The ominious api folder that you find in all our client apps is actually entirely generated from the GraphQL schema, that you find in the schema folder. This means you can generate your own typed queries and mutations from the schema.