[ENHANCEMENT]: Simplify Administrative Operations with REST API

[Joaquin Menchaca]

Use case and current behavior

The current state of administrative operations using GraphQL within Dgraph presents challenges that hinder a seamless user experience. These complexities not only impede the ease of utilizing Dgraph but also complicate the management of administrative tasks. A more streamlined approach to accessing and executing administrative functions is essential to enhance the overall usability of Dgraph.

At present, the process of managing administrative operations via GraphQL is marked by intricacies and unwieldiness, ultimately introducing friction into the user journey. One particular pain point lies in the accessibility of Dgraph's administrative functionalities, such as binary backups, which necessitates the creation of intricate programs. This poses a significant obstacle for operators aiming to automate these tasks efficiently.

For instance, resorting to tools like curl to interact with the GraphQL interface presents a persistent challenge—each query or mutation triggers an HTTP OK response, masking potential errors. Consequently, automating operations becomes a convoluted endeavor, requiring the parsing of JSON responses to detect errors. This task is compounded by the intricacies of error processing.

Consider the scenario of automating processes through a Kubernetes cronjob resource object. This mandates the creation of specialized container images embedded with auxiliary tools like jq or gron. Additionally, resorting to techniques like perl regular expressions or even developing custom programs becomes a necessity to facilitate essential tasks like backups. However, the need for such elaborate workarounds contradicts the notion of streamlined administrative access within Dgraph.

As an example (Kubernetes cronjob) doing administrative operation for doing a binary backup:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: my-dgraph-backup
  namespace: dgraph
spec:
  jobTemplate:
    spec:
      template:
        metadata:
          creationTimestamp: null
        spec:
          containers:
          - args:
            - |
              RESULT=$(curl http://my-dgraph-alpha-0.my-dgraph-alpha-headless:8080/admin --silent --request POST \
                --header "Content-Type: application/graphql" \
                --data "mutation { backup(input: {destination: \"s3:\/\/\/prod-dgraph-backups/$(date +%Y-%m-%d)\"}) { response { message code } taskId }}");
                echo $RESULT;
                echo $RESULT | grep -q '"code":"Success"' || exit 1
            command:
            - /bin/sh
            - -c
            image: curlimages/curl:8.2.1

Enhancement

In comparison to the current GraphQL-centric approach, leveraging a REST API offers a more streamlined and less complex method for managing Dgraph operations. A REST API not only reduces friction but also simplifies the task of writing automation scripts. Crucially, the REST API's inherent error handling mechanism ensures that in the event of a process failure, responses beyond the HTTP OK status code are returned. This mechanism, in turn, enables more accurate failure detection, fostering enhanced monitoring capabilities, especially when combined with tools like Kubernetes cronjob resources and Prometheus.

The distinct advantage of the REST API lies in its straightforwardness. Simplified and direct communication with Dgraph fosters a smoother experience, mitigating the need for intricate workarounds or the manual parsing of JSON responses. As processes encounter setbacks, the API's ability to convey meaningful error codes empowers operators to precisely pinpoint issues, leading to more efficient troubleshooting.

Consider the context of automation and scheduling, as exemplified by a Kubernetes cronjob resource. By integrating Dgraph's REST API, failures in scheduled tasks are distinctly indicated, triggering responses beyond the standard HTTP OK. This outcome facilitates the seamless integration of Prometheus monitoring, allowing operators to proactively identify and address potential problems, ensuring the continued smooth functioning of Dgraph operations.

In essence, adding an REST API-driven approach represents a marked enhancement in managing Dgraph. It simplifies processes, amplifies error detection, and fortifies automation efforts, all of which collectively contribute to an elevated level of operational efficiency and a more user-friendly experience.

Here's an example of a Kubernetes cronjob to send backup requests to Dgraph:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: my-simple-dgraph-backup
  namespace: dgraph
spec:
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - command:
            - /bin/sh
            - -c
            - curl --silent -XPOST http://my-dgraph-alpha-0.my-dgraph-alpha-headless:8080/admin/backup
              -d "destination=s3:///prod-dgraph-backups/$(date +%Y-%m-%d)"
            image: curlimages/curl:8.2.1

Solution proposal

Add REST API for administrative operations and use OpenAPI compliant API with self documentation endpoint for the API.

Links to Discuss, RFC or previous Issues and PRs

No response

Links to examples and research

No response

Additional Information

No response

[github-actions]

This issue has been stale for 60 days and will be closed automatically in 7 days. Comment to keep it open.