Make the API easier / friendlier to use

GraphQL is a new skill for REST developers. This post is not about GQL. I think GQL is great. This feedback is about everything Spacelift do to make the Developer Experience 10x worse than it could be.

When the Spacelift API is difficult to use, it discourages growth of an ecosystem around the API. There are no utilities or apps of note using the Spacelift API and I believe part of the reason is that the API is so difficult to use.

1. The documentation is sparse writing + looms

cosmetically, the page is a nightmare. Many images are poorly sized and it’s hard to keep track of where you are in the header hierarchy.

Understanding how to authenticate is fundamental, and yet it is poorly documented. The key idea is “Add a header Authorization: bearer $YOUR_JWT but you won’f find this written on the page anywhere! (If you look closely, it’s in a code snippet) Instead we document five ways to get a JWT. One of which is specific to Github Actions. Two of which are only relevant for personal testing (spacectl & PAT).

The docs and UX for getting a static API key suck. You’re forced to download a file containing the secret rather than copy to clipboard. The file contains two secrets and it’s not clear how they differ. The file also doesn’t contain the key ID, which is required during authentication. You have to go back a step, find your new key in the web UI, and copy the ID manually.

Docs for graphiql are simply wrong and do not explain how to authenticate (which is required to access schema).

2. No schema is published, adding a hoop to codegen users (figuring out how to authenticate without having the schema)

I spent 30mins trying to do this and eventually figured out the magical incantation:
npx get-graphql-schema https://demo.app.spacelift.io/graphql > schema.graphql

I still have no idea how to download the schema from our own account subdomain, despite Spacelift staff insisting that using the wrong schema will lead to ruin.

Major companies like Github and Shopify run graphql APIs, and they can publish easily accessible URLs to download their schema. There’s no reason Spacelift cannot do the same.

3 There are only two sources of existing code to learn from. spacectl and

https://github.com/spacelift-io/spacelift-api-examples which both have no “client sdk” layer and rely on non-reusable gql queries plus untyped JSON unmarshalling

Please make API development better.