Maintain REST API as first-class citizen

Features Requests
1

I noticed the GraphQL/REST feature parity post, and while i absolutely support feature parity for both apis, I have concerns about GraphQL being the way forward. While GraphQL is great for rich apps, a lot automation is done via cURL, which is basically incompatible with GraphQL.

2

Hey there @ianwremmel :wave:t3:

Thanks for posting, and thanks for the feedback! In general we actually think that GraphQL is a pretty great all-rounder for most uses, and our goal of moving towards it will let us focus more on building new features faster, better, etc.

I’m interested that you feel that curl and gQL are incompatible though, as we’ve certainly found the opposite! We often make use of the graphql endpoint via just bash with a bit of help from jq — check it out;

#!/usr/bin/env bash
set -euo pipefail

# Query to fetch the current pipeline GraphQL ID using the pipeline slug
read -r -d '' PipelineQuery <<'EOF'
query PipelineQuery($pipelineSlug: ID!) {
  pipeline(slug: $pipelineSlug) {
    id
  }
}
EOF

# Utility function to perform a GraphQL request to the Buildkite GraphQL
# server. Takes a query or mutation, and optionally any required variables.
function graphql() {
  local query variables payload;

  query="$1"
  variables="$2"
  payload=$(jq '{$query, $variables}' -rncMS --arg query "$query" --argjson variables "$variables")

  curl -s https://graphql.buildkite.com/v1 -X POST -H "Authorization: Bearer $BUILDKKTE_ACCESS_TOKEN" -d "$payload"
}

function main() {
  graphql "$PipelineQuery" "$(jq '{$pipelineSlug}' -rncMS --arg pipelineSlug your-org/pipeline-slug)"
}

main
3

Hi @justin,

I guess that seems like a lot of boilerplate most of us never would have had the time to figure out in order to achieve the following:

ORG_SLUG=your-org/pipeline-slug
curl -H "Authorization: Bearer ${BUILDKITE_ACCESS_TOKEN}" \
    "https://api.buildkite.com/v2/organizations/$ORG_SLUG/pipelines"

or

ORG_SLUG=your-org/pipeline-slug
http "https://api.buildkite.com/v2/organizations/$ORG_SLUG/pipelines" \
    Authorization:"Bearer ${BUILDKITE_ACCESS_TOKEN}"

Similarly, it was recently pointed out to me how powerful it is for (what would typically be) a json api to also accept form-encoded payloads, since you don’t have to figure out how to encode json on the command line and can just use cURL’s -F switch.

graphql is really difficult (technically impossible?) to write as a one-liner, which makes it difficult to experiment from a command line. I understand the in-browser explorer can be super-powerful, but if I’m sshed into a box and I’ve only got terminal, I don’t want to have to open a text editor to write a thirty-line script if I can just hit a REST endpoint.

I’m all for using graphql in complex plugins, or things like a Terraform provider but for smaller cases where folks just need to get something done quickly, continuing to treat REST as a first-class system seems really important.

Granted, it’s still better than hitting the Jenkins XML api :slight_smile:

4

Hey @ianwremmel, I hear you it’s certainly more boilerplate—that’s totally fair. :slightly_smiling_face:

To be clear we’re still working through options here, and exploring what all this might looks like down the track.

One thing we’re pretty sure about is that GraphQL will certainly play a large role in the API surface area we present, though there is certainly room in the discussion for other implementations that could potentially augment it, and be used for less complex cases like you’ve mentioned.