この記事の対象読者

Linear公式のGraphQL APIページを見て、Pythonでクエリを試したがうまくいかなかった人
https://developers.linear.app/docs/graphql/working-with-the-graphql-api

忙しい人は、以下にコードを公開していますので読むと速い。
https://github.com/akjava/python-linear-api-examples/tree/main/examples/api

上記のページのクエリをすべて動く、サンプルを分けて、intro*.pyで作ってみました。

クエリとは、GraphQL APIに対してデータを要求するための以下のようなテキストのこと

   query Me {
  viewer {
    id
    name
    email
  }
}

GraphQLとは

GraphQLは、RESTと同じようにHTTPプロトコルを使って通信しますが、より効率的なデータ取得を実現します。

より詳しくは、公式の英文をAIに聞く方が正確でしょう。https://graphql.org/

PythonでLinear APIを呼び出し時の注意点

GraphQLは、他に使ったことないので、同じかどうかはわかりません。

queryで送る

queryでも、mutationでも、queryとして送るみたいです。

query_dic = {"query": query_text}
...
response = requests.post(url, headers=headers, json=query_dic)

返ってきた値から目的値の取得

例として、送ったのが以下の構造だと(なお、大文字から始まるTeamsは何の意味もないです)

query Teams {
  teams {
    nodes {
      id
      name
    }
  }
}

最初にdataがつけて、値を取り出します。

first_team_id = result["data"]["teams"]["nodes"][0]["id"]

削除したデータの取得

基本、削除されたデータは３０日間のArchived状態になります。そしてデフォルトでは取れません。
まず、includeArchived: true は必須です。
公式のドキュメントには書いてませんでしたが、archivedAtの値（日付）があるデータだけを取るにはnullフィルターを使うのがいいと思います。

query {
  issues(includeArchived: true,filter:{
    archivedAt:{
      null:false
      }
  }) {
    nodes {
      title
      archivedAt
    }
  }
}

まとめ

基本的に、pythonでもページにのっている、クエリをそのままコピーして送りつけると動きます。

あと Linear API(GraphQL)はエラーの内容が詳細に返ってくるのでメッセージを良く読みましょう。
テキスト量が多いと思ったより遅いので更新内容だけとる工夫をしないと、数が多い時に大変です。

しばらくはLinear記事続きますので、今後ともよろしく。

Github
https://github.com/akjava/python-linear-api-examples