From d00b431f58a64da02ae31f5638f2277d98d5fe49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javi=20Mart=C3=ADn?= Date: Tue, 17 Sep 2024 15:45:30 +0200 Subject: [PATCH] Move GraphQL code examples to the GraphQL docs While this leads to a bit of duplication, since now the same code is in both the Spanish and English texts, and it makes it harder to actually run the code, it'll make it easier for people reading the documentation to find the code, and we get rid of the confusingly-named `doc/` folder. --- doc/api/examples/ruby/example_1.rb | 29 -------- doc/api/examples/ruby/example_2.rb | 68 ----------------- docs/en/features/graphql.md | 113 ++++++++++++++++++++++++++++- docs/es/features/graphql.md | 113 ++++++++++++++++++++++++++++- 4 files changed, 224 insertions(+), 99 deletions(-) delete mode 100644 doc/api/examples/ruby/example_1.rb delete mode 100644 doc/api/examples/ruby/example_2.rb diff --git a/doc/api/examples/ruby/example_1.rb b/doc/api/examples/ruby/example_1.rb deleted file mode 100644 index 03cc1d41f..000000000 --- a/doc/api/examples/ruby/example_1.rb +++ /dev/null @@ -1,29 +0,0 @@ -require "net/http" - -API_ENDPOINT = "https://demo.consuldemocracy.org/graphql".freeze - -def make_request(query_string) - uri = URI(API_ENDPOINT) - uri.query = URI.encode_www_form(query: query_string) - request = Net::HTTP::Get.new(uri) - request[:accept] = "application/json" - - Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |https| - https.request(request) - end -end - -query = <<-GRAPHQL - { - proposal(id: 1) { - id, - title, - public_created_at - } - } -GRAPHQL - -response = make_request(query) - -puts "Response code: #{response.code}" -puts "Response body: #{response.body}" diff --git a/doc/api/examples/ruby/example_2.rb b/doc/api/examples/ruby/example_2.rb deleted file mode 100644 index 22b3e19d3..000000000 --- a/doc/api/examples/ruby/example_2.rb +++ /dev/null @@ -1,68 +0,0 @@ -require "net/http" -require "json" - -API_ENDPOINT = "https://demo.consuldemocracy.org/graphql".freeze - -def make_request(query_string) - uri = URI(API_ENDPOINT) - uri.query = URI.encode_www_form(query: query_string) - request = Net::HTTP::Get.new(uri) - request[:accept] = "application/json" - - Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |https| - https.request(request) - end -end - -def build_query(options = {}) - page_size = options[:page_size] || 25 - page_size_parameter = "first: #{page_size}" - - page_number = options[:page_number] || 0 - after_parameter = page_number.positive? ? ", after: \"#{options[:next_cursor]}\"" : "" - - <<-GRAPHQL - { - proposals(#{page_size_parameter}#{after_parameter}) { - pageInfo { - endCursor, - hasNextPage - }, - edges { - node { - id, - title, - public_created_at - } - } - } - } - GRAPHQL -end - -page_number = 0 -next_cursor = nil -proposals = [] - -loop do - puts "> Requesting page #{page_number}" - - query = build_query(page_size: 25, page_number: page_number, next_cursor: next_cursor) - response = make_request(query) - - response_hash = JSON.parse(response.body) - page_info = response_hash["data"]["proposals"]["pageInfo"] - has_next_page = page_info["hasNextPage"] - next_cursor = page_info["endCursor"] - proposal_edges = response_hash["data"]["proposals"]["edges"] - - puts "\tHTTP code: #{response.code}" - - proposal_edges.each do |edge| - proposals << edge["node"] - end - - page_number += 1 - - break unless has_next_page -end diff --git a/docs/en/features/graphql.md b/docs/en/features/graphql.md index 2496dfedf..01614abaa 100644 --- a/docs/en/features/graphql.md +++ b/docs/en/features/graphql.md @@ -17,6 +17,8 @@ * [Example of a query which is too deep](#example-of-a-query-which-is-too-deep) * [Example of a query which is too complex](#example-of-a-query-which-is-too-complex) * [Code examples](#code-examples) + * [Simple example](#simple-example) + * [Example with pagination](#example-with-pagination) ## Characteristics @@ -425,4 +427,113 @@ The response: ## Code examples -The [doc/api/examples](https://github.com/consuldemocracy/consuldemocracy/tree/master/doc/api/examples/ruby) directory contains examples of code to access the API. +### Simple example + +Here's a simple example of code accessing the Consul Democracy demo API: + +```ruby +require "net/http" + +API_ENDPOINT = "https://demo.consuldemocracy.org/graphql".freeze + +def make_request(query_string) + uri = URI(API_ENDPOINT) + uri.query = URI.encode_www_form(query: query_string) + request = Net::HTTP::Get.new(uri) + request[:accept] = "application/json" + + Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |https| + https.request(request) + end +end + +query = <<-GRAPHQL + { + proposal(id: 1) { + id, + title, + public_created_at + } + } +GRAPHQL + +response = make_request(query) + +puts "Response code: #{response.code}" +puts "Response body: #{response.body}" +``` + +### Example with pagination + +And here is a more complex example using pagination, once again accessing the Consul Democracy demo API: + +```ruby +require "net/http" +require "json" + +API_ENDPOINT = "https://demo.consuldemocracy.org/graphql".freeze + +def make_request(query_string) + uri = URI(API_ENDPOINT) + uri.query = URI.encode_www_form(query: query_string) + request = Net::HTTP::Get.new(uri) + request[:accept] = "application/json" + + Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |https| + https.request(request) + end +end + +def build_query(options = {}) + page_size = options[:page_size] || 25 + page_size_parameter = "first: #{page_size}" + + page_number = options[:page_number] || 0 + after_parameter = page_number.positive? ? ", after: \"#{options[:next_cursor]}\"" : "" + + <<-GRAPHQL + { + proposals(#{page_size_parameter}#{after_parameter}) { + pageInfo { + endCursor, + hasNextPage + }, + edges { + node { + id, + title, + public_created_at + } + } + } + } + GRAPHQL +end + +page_number = 0 +next_cursor = nil +proposals = [] + +loop do + puts "> Requesting page #{page_number}" + + query = build_query(page_size: 25, page_number: page_number, next_cursor: next_cursor) + response = make_request(query) + + response_hash = JSON.parse(response.body) + page_info = response_hash["data"]["proposals"]["pageInfo"] + has_next_page = page_info["hasNextPage"] + next_cursor = page_info["endCursor"] + proposal_edges = response_hash["data"]["proposals"]["edges"] + + puts "\tHTTP code: #{response.code}" + + proposal_edges.each do |edge| + proposals << edge["node"] + end + + page_number += 1 + + break unless has_next_page +end +``` diff --git a/docs/es/features/graphql.md b/docs/es/features/graphql.md index 95d08e28d..dc0fcd151 100644 --- a/docs/es/features/graphql.md +++ b/docs/es/features/graphql.md @@ -17,6 +17,8 @@ * [Ejemplo de consulta demasiado profunda](#ejemplo-de-consulta-demasiado-profunda) * [Ejemplo de consulta demasiado compleja](#ejemplo-de-consulta-demasiado-compleja) * [Ejemplos de código](#ejemplos-de-codigo) + * [Ejemplo sencillo](#ejemplo-sencillo) + * [Ejemplo con paginación](#ejemplo-con-paginacion)

Características

@@ -425,4 +427,113 @@ La respuesta:

Ejemplos de código

-El directorio [doc/api/examples](https://github.com/consuldemocracy/consuldemocracy/tree/master/doc/api/examples/ruby) contiene ejemplos de código para acceder a la API. +### Ejemplo sencillo + +Este es un ejemplo sencillo de código accediendo a la API de la demo de Consul Democracy: + +```ruby +require "net/http" + +API_ENDPOINT = "https://demo.consuldemocracy.org/graphql".freeze + +def make_request(query_string) + uri = URI(API_ENDPOINT) + uri.query = URI.encode_www_form(query: query_string) + request = Net::HTTP::Get.new(uri) + request[:accept] = "application/json" + + Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |https| + https.request(request) + end +end + +query = <<-GRAPHQL + { + proposal(id: 1) { + id, + title, + public_created_at + } + } +GRAPHQL + +response = make_request(query) + +puts "Response code: #{response.code}" +puts "Response body: #{response.body}" +``` + +

Ejemplo con paginación

+ +Y este es un ejemplo un tanto más complejo usando paginación, una vez más accediendo a la API de la demo de Consul Democracy: + +```ruby +require "net/http" +require "json" + +API_ENDPOINT = "https://demo.consuldemocracy.org/graphql".freeze + +def make_request(query_string) + uri = URI(API_ENDPOINT) + uri.query = URI.encode_www_form(query: query_string) + request = Net::HTTP::Get.new(uri) + request[:accept] = "application/json" + + Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |https| + https.request(request) + end +end + +def build_query(options = {}) + page_size = options[:page_size] || 25 + page_size_parameter = "first: #{page_size}" + + page_number = options[:page_number] || 0 + after_parameter = page_number.positive? ? ", after: \"#{options[:next_cursor]}\"" : "" + + <<-GRAPHQL + { + proposals(#{page_size_parameter}#{after_parameter}) { + pageInfo { + endCursor, + hasNextPage + }, + edges { + node { + id, + title, + public_created_at + } + } + } + } + GRAPHQL +end + +page_number = 0 +next_cursor = nil +proposals = [] + +loop do + puts "> Requesting page #{page_number}" + + query = build_query(page_size: 25, page_number: page_number, next_cursor: next_cursor) + response = make_request(query) + + response_hash = JSON.parse(response.body) + page_info = response_hash["data"]["proposals"]["pageInfo"] + has_next_page = page_info["hasNextPage"] + next_cursor = page_info["endCursor"] + proposal_edges = response_hash["data"]["proposals"]["edges"] + + puts "\tHTTP code: #{response.code}" + + proposal_edges.each do |edge| + proposals << edge["node"] + end + + page_number += 1 + + break unless has_next_page +end +```