From f5f6c3da37fc8f481a27ccd64615620f757f97cf Mon Sep 17 00:00:00 2001 From: WHLukasz Date: Thu, 10 Oct 2024 14:14:56 +0200 Subject: [PATCH 1/3] #25491 add description on fetching single cto with custom field using graphql --- docs/API/graph-ql.md | 284 +++++++++++++++++++++++++------------------ 1 file changed, 169 insertions(+), 115 deletions(-) diff --git a/docs/API/graph-ql.md b/docs/API/graph-ql.md index 2896749b..4cb698a3 100644 --- a/docs/API/graph-ql.md +++ b/docs/API/graph-ql.md @@ -12,7 +12,7 @@ which understands GraphQL queries for your Content Objects. ## What is a GraphQL? GraphQL is a query language for APIs. -It is designed to make API more flexible than REST API - it is all about giving clients precisely the data they request. +It is designed to make API more flexible than REST API - it is all about giving clients precisely the data they request. The developers can pull various data, in the desired shape, with a single API call. ## Graphql in Flotiq @@ -46,14 +46,13 @@ To get the full GraphQL schema that describes your data you have to call the GET It describes the shape of your current Content Type Definitions, including attribute types, required fields and relations. - !!! Request ``` curl -X GET 'https://api.flotiq.com/api/graphql/schema' --header 'X-AUTH-TOKEN: YOUR_API_TOKEN' ``` { data-search-exclude } -!!! Responses +!!! Response === "200 OK" @@ -124,45 +123,97 @@ We can specify two types of queries - responsible for retrieving a single object #### Query single object -To a get single object, you need to pass the object identifier and fields you want to receive in the response. +To a get single object, you need to pass the object identifier and fields you want to receive in the response. Example Query in GraphQL language to get `id` and `title` for the product with id `product-1` looks like: -!!! GraphQL query +!!! Example - ```graphql - query { - products(id:"product-1") { - id - title - } - } - ``` - { data-search-exclude } + === "Use id to fetch object" -To pass this query to the Flotiq, you need to call: + The most straight-forward way of querying your Flotiq single object with GraphQL is to use the objects ID: -!!! Request - ``` - curl -X POST 'https://api.flotiq.com/api/graphql' \ - --header 'X-AUTH-TOKEN: YOUR_API_TOKEN' \ - --header 'Content-Type: application/json' \ - --data-raw '{"query":"query{products(id:\"product-1\"){id,title,}}"}' - ``` - { data-search-exclude } + !!! GraphQL query -!!! Response - === "200 OK" - ```json - { - "data": { - "products": { - "id": "product-1", - "title": "Green Tea" + ```graphql + query { + products(id:"product-1") { + id + title } } - } - ``` - { data-search-exclude } + ``` + { data-search-exclude } + + To pass this query to the Flotiq, you need to call: + + !!! Request + ``` + curl -X POST 'https://api.flotiq.com/api/graphql' \ + --header 'X-AUTH-TOKEN: YOUR_API_TOKEN' \ + --header 'Content-Type: application/json' \ + --data-raw '{"query":"{ products(id: \"product-1\") { id title } }"}' + ``` + { data-search-exclude } + + !!! Response + === "200 OK" + ```json + { + "data": { + "products": { + "id": "product-1", + "title": "Green Tea" + } + } + } + ``` + { data-search-exclude } + + === "Use custom field to fetch object" + + You can use your own field from your content type definition to query Flotiq data with GraphQL. + To do so, your content type definition has to have a text field with [unique property](../panel/content-types.md?h=unique#property-settings). + This will allow you to query objects of that type using arguments: + + - field: ``, + - value: `` + + !!! GraphQL query + + ```graphql + query { + products(field: "title", value: "Green Tea") { + id + title + } + } + ``` + { data-search-exclude } + + To pass this query to the Flotiq, you need to call: + + !!! Request + ``` + curl -X POST 'https://api.flotiq.com/api/graphql' \ + --header 'X-AUTH-TOKEN: YOUR_API_TOKEN' \ + --header 'Content-Type: application/json' \ + --data-raw '{"query":"{ products(field: \"title\", value: \"Green Tea\") { id title } }"}' + ``` + { data-search-exclude } + + !!! Response + === "200 OK" + ```json + { + "data": { + "products": { + "id": "product-1", + "title": "Green Tea" + } + } + } + ``` + { data-search-exclude } #### List objects @@ -179,49 +230,51 @@ While listing objects, you can use the optional parameters The below example shows how to list all products ordered by title, limited to 2 results: -!!! GraphQL query - ```graphql - query { - productsList(limit: 2, order_by: "title", order_direction: "asc") { - id - title - } - } - ``` - { data-search-exclude } - -To pass this query to the Flotiq, you need to call: +!!! Example -!!! Request - ``` - curl -X POST 'https://api.flotiq.com/api/graphql' \ - --header 'X-AUTH-TOKEN: YOUR_API_TOKEN' \ - --header 'Content-Type: application/json' \ - --data-raw '{"query":"query {productsList(limit: 2, order_by: \"title\", order_direction: \"desc\") {id, title}}"}' - ``` - { data-search-exclude } + !!! GraphQL query + ```graphql + query { + productsList(limit: 2, order_by: "title", order_direction: "asc") { + id + title + } + } + ``` + { data-search-exclude } -!!! Response + To pass this query to the Flotiq, you need to call: - === "200 OK" - ```json - { - "data": { - "productsList": [ - { - "id": "product-3", - "title": "Rooibos" - }, - { - "id": "product-2", - "title": "Earl Grey" - } - ] - } - } + !!! Request + ``` + curl -X POST 'https://api.flotiq.com/api/graphql' \ + --header 'X-AUTH-TOKEN: YOUR_API_TOKEN' \ + --header 'Content-Type: application/json' \ + --data-raw '{"query":"query {productsList(limit: 2, order_by: \"title\", order_direction: \"desc\") {id, title}}"}' ``` { data-search-exclude } + !!! Response + + === "200 OK" + ```json + { + "data": { + "productsList": [ + { + "id": "product-3", + "title": "Rooibos" + }, + { + "id": "product-2", + "title": "Earl Grey" + } + ] + } + } + ``` + { data-search-exclude } + ### Relation resolving (hydration) GraphQLs flexibility also covers object relations (e.g. product has category). @@ -241,7 +294,7 @@ For example, when we have a product object: ``` { data-search-exclude } -and category: +and category: ```json { "id": "category-1", @@ -252,56 +305,57 @@ and category: The GraphQL query for listing objects including categories will look like: -!!! GraphQL query - ```graphql - query { - productsList(limit: 1) { - id - title - categories { - id - name - } - } - } - ``` - { data-search-exclude } - -!!! Request - ``` - curl --request POST \ - --url 'https://api.flotiq.com/api/graphql?auth_token=__YOUR_AUTH_TOKEN__' \ - --header 'content-type: application/json' \ - --data '{"query":"query{productsList(limit:1){id,title,categories{id,name}}}"}' - ``` - { data-search-exclude } +!!! Example -!!! Response - - === "200 OK" - Will return automatically resolved relation: - ```json - { - "data": { - "productsList": [ - { - "id": "product-3", - "title": "Rooibos", - "categories": [ - { - "id": "category-1", - "name": "Tea" - } - ] - } - ] + !!! GraphQL query + ```graphql + query { + productsList(limit: 1) { + id + title + categories { + id + name + } } } ``` { data-search-exclude } -As you can see, the related element, `category`, was fetched, including its properties. + !!! Request + ``` + curl --request POST \ + --url 'https://api.flotiq.com/api/graphql?auth_token=__YOUR_AUTH_TOKEN__' \ + --header 'content-type: application/json' \ + --data '{"query":"query{productsList(limit:1){id,title,categories{id,name}}}"}' + ``` + { data-search-exclude } + + !!! Response + + === "200 OK" + Will return automatically resolved relation: + ```json + { + "data": { + "productsList": [ + { + "id": "product-3", + "title": "Rooibos", + "categories": [ + { + "id": "category-1", + "name": "Tea" + } + ] + } + ] + } + } + ``` + { data-search-exclude } + As you can see, the related element, `category`, was fetched, including its properties. ## Explore using Insomnia client From f3f6efc82b7d2e9f7d05aa8554bfd4c53a14819d Mon Sep 17 00:00:00 2001 From: WHLukasz Date: Thu, 10 Oct 2024 14:15:47 +0200 Subject: [PATCH 2/3] minor fixes and typos #25491 --- docs/API/content-type/creating-co.md | 2 +- docs/API/content-type/creating-ctd.md | 2 +- docs/API/content-type/deleting-co.md | 2 +- docs/API/content-type/deleting-ctd.md | 2 +- docs/API/content-type/getting-co.md | 2 +- docs/API/content-type/getting-ctd.md | 2 +- docs/API/content-type/listing-co.md | 2 +- docs/API/content-type/listing-ctd.md | 2 +- docs/API/content-type/updating-co.md | 2 +- docs/API/content-type/updating-ctd.md | 4 +- docs/API/get-started.md | 185 +++++++++++++------------- docs/CLI/excel-data-migration.md | 4 +- 12 files changed, 105 insertions(+), 106 deletions(-) diff --git a/docs/API/content-type/creating-co.md b/docs/API/content-type/creating-co.md index 85c7f650..0a5fe4b8 100644 --- a/docs/API/content-type/creating-co.md +++ b/docs/API/content-type/creating-co.md @@ -193,7 +193,7 @@ to the supporting endpoint `https://api.flotiq.com/api/v1/content/{name}` ``` { data-search-exclude } -!!! Responses +!!! Response === "200 OK" diff --git a/docs/API/content-type/creating-ctd.md b/docs/API/content-type/creating-ctd.md index 480a079f..a763509a 100644 --- a/docs/API/content-type/creating-ctd.md +++ b/docs/API/content-type/creating-ctd.md @@ -345,7 +345,7 @@ The first input in the form in the CMS panel will be `title` input, and the seco ``` { data-search-exclude } -!!! Responses +!!! Response === "200 OK" diff --git a/docs/API/content-type/deleting-co.md b/docs/API/content-type/deleting-co.md index 48613b8a..5e272ffc 100644 --- a/docs/API/content-type/deleting-co.md +++ b/docs/API/content-type/deleting-co.md @@ -150,7 +150,7 @@ Deleting is done by sending `DELETE` request to `https://api.flotiq.com/api/v1/c { data-search-exclude } -!!! Responses +!!! Response === "204 OK" diff --git a/docs/API/content-type/deleting-ctd.md b/docs/API/content-type/deleting-ctd.md index ad035bdb..fda321e0 100644 --- a/docs/API/content-type/deleting-ctd.md +++ b/docs/API/content-type/deleting-ctd.md @@ -153,7 +153,7 @@ You can only delete Content Types that do not have any Content Objects or are no ``` { data-search-exclude } -!!! Responses +!!! Response === "200 OK" diff --git a/docs/API/content-type/getting-co.md b/docs/API/content-type/getting-co.md index f76a65cb..14c7c660 100644 --- a/docs/API/content-type/getting-co.md +++ b/docs/API/content-type/getting-co.md @@ -160,7 +160,7 @@ Request parameters | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | | hydrate | If you want to hydrate data sources in the object, you need to set it to `1`, it will hydrate one level of data sources in objects, `2` will hydrate deeper objects, and it's the highest level of hydration available in Flotiq API | -!!! Responses +!!! Response === "200 OK" diff --git a/docs/API/content-type/getting-ctd.md b/docs/API/content-type/getting-ctd.md index c7387eeb..9eff57f5 100644 --- a/docs/API/content-type/getting-ctd.md +++ b/docs/API/content-type/getting-ctd.md @@ -152,7 +152,7 @@ Possible request parameters: ``` { data-search-exclude } -!!! Responses +!!! Response === "200 OK" diff --git a/docs/API/content-type/listing-co.md b/docs/API/content-type/listing-co.md index 9808e297..c2a5de98 100644 --- a/docs/API/content-type/listing-co.md +++ b/docs/API/content-type/listing-co.md @@ -322,7 +322,7 @@ Request parameters | hydrate | If you want to hydrate data sources in the object, you need to set it to `1`, it will hydrate one level of data sources in objects, `2` will hydrate deeper objects, and it's the highest level of hydration available in Flotiq API. You can also use this parameter when requesting a single object | | filters | Json encoded object containing conditions on which the list of CO should be filtered. | -!!! Responses +!!! Response === "200 OK" diff --git a/docs/API/content-type/listing-ctd.md b/docs/API/content-type/listing-ctd.md index 6c4e5f78..2f464177 100644 --- a/docs/API/content-type/listing-ctd.md +++ b/docs/API/content-type/listing-ctd.md @@ -163,7 +163,7 @@ Possible request parameters: ``` { data-search-exclude } -!!! Responses +!!! Response === "200 OK" diff --git a/docs/API/content-type/updating-co.md b/docs/API/content-type/updating-co.md index d28ffb01..4bf3e55b 100644 --- a/docs/API/content-type/updating-co.md +++ b/docs/API/content-type/updating-co.md @@ -191,7 +191,7 @@ to the supporting endpoint `https://api.flotiq.com/api/v1/content/{name}/{id}` t { data-search-exclude } -!!! Responses +!!! Response === "200 OK" diff --git a/docs/API/content-type/updating-ctd.md b/docs/API/content-type/updating-ctd.md index 77c0fb5a..efa58de2 100644 --- a/docs/API/content-type/updating-ctd.md +++ b/docs/API/content-type/updating-ctd.md @@ -330,7 +330,7 @@ When you change existing property, depending on the type of changes, Flotiq will ``` { data-search-exclude } -!!! Responses +!!! Response === "200 OK" @@ -455,7 +455,7 @@ When you modify a schema, any associated objects undergo a transformation proces When encountering issues during schema conversion, you might receive error messages like the following: -!!! Responses +!!! Response === "400 Validation error" diff --git a/docs/API/get-started.md b/docs/API/get-started.md index 066e5d41..8ca04617 100644 --- a/docs/API/get-started.md +++ b/docs/API/get-started.md @@ -156,7 +156,7 @@ Retrieve the schema of a specific Content Object by sending a `GET` request to t ``` { data-search-exclude } -!!! Responses +!!! Response === "200 OK" @@ -229,125 +229,124 @@ To pass this query to the Flotiq, you need to call: !!! Example -=== "CURL" + === "CURL" - ``` - curl -X POST 'https://api.flotiq.com/api/graphql' \ - --header 'X-AUTH-TOKEN: YOUR_API_TOKEN' \ - --header 'Content-Type: application/json' \ - --data-raw '{"query":"query { blogposts(id: \"blogposts-456712\") { id title } }"}' - ``` - { data-search-exclude } + ``` + curl -X POST 'https://api.flotiq.com/api/graphql' \ + --header 'X-AUTH-TOKEN: YOUR_API_TOKEN' \ + --header 'Content-Type: application/json' \ + --data-raw '{"query":"query { blogposts(id: \"blogposts-456712\") { id title } }"}' + ``` + { data-search-exclude } -=== "JavaScript + Fetch" + === "JavaScript + Fetch" - ``` - fetch('https://api.flotiq.com/api/graphql', { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - 'X-AUTH-TOKEN': 'YOUR_API_TOKEN' - }, - body: JSON.stringify({ + ``` + fetch('https://api.flotiq.com/api/graphql', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'X-AUTH-TOKEN': 'YOUR_API_TOKEN' + }, + body: JSON.stringify({ + query: 'query { blogposts(id: "blogposts-456712") { id title } }' + }) + }) + .then(response => response.json()) + .then(data => console.log(data)); + ``` + { data-search-exclude } + + === "Node + Axios" + + ``` + const axios = require('axios'); + + axios.post('https://api.flotiq.com/api/graphql', { query: 'query { blogposts(id: "blogposts-456712") { id title } }' + }, { + headers: { + 'Content-Type': 'application/json', + 'X-AUTH-TOKEN': 'YOUR_API_TOKEN' + } }) - }) - .then(response => response.json()) - .then(data => console.log(data)); - ``` - { data-search-exclude } + .then(response => console.log(response.data)) + .catch(error => console.log(error)); + ``` + { data-search-exclude } -=== "Node + Axios" + === "Python + Requests" - ``` - const axios = require('axios'); + ``` + import requests - axios.post('https://api.flotiq.com/api/graphql', { - query: 'query { blogposts(id: "blogposts-456712") { id title } }' - }, { - headers: { + url = 'https://api.flotiq.com/api/graphql' + headers = { 'Content-Type': 'application/json', 'X-AUTH-TOKEN': 'YOUR_API_TOKEN' } - }) - .then(response => console.log(response.data)) - .catch(error => console.log(error)); - ``` - { data-search-exclude } - -=== "Python + Requests" - - ``` - import requests - - url = 'https://api.flotiq.com/api/graphql' - headers = { - 'Content-Type': 'application/json', - 'X-AUTH-TOKEN': 'YOUR_API_TOKEN' - } - data = { - 'query': 'query { blogposts(id: "blogposts-456712") { id title } }' - } + data = { + 'query': 'query { blogposts(id: "blogposts-456712") { id title } }' + } - response = requests.post(url, headers=headers, json=data) - print(response.json()) - ``` - { data-search-exclude } + response = requests.post(url, headers=headers, json=data) + print(response.json()) + ``` + { data-search-exclude } !!! Response -=== "200 OK" + === "200 OK" - Returned when the object was found + Returned when the object was found - ```json - { - "data": { - "blogposts": { - "id": "blogposts-456712", - "title": "New object" + ```json + { + "data": { + "blogposts": { + "id": "blogposts-456712", + "title": "New object" + } } } - } - ``` - { data-search-exclude } + ``` + { data-search-exclude } -=== "401 Unauthorized" + === "401 Unauthorized" - Returned when the API key was missing or incorrect + Returned when the API key was missing or incorrect - ```json - { - "errors": [ - { - "message": "Unauthorized", - "extensions": { - "code": "UNAUTHORIZED" + ```json + { + "errors": [ + { + "message": "Unauthorized", + "extensions": { + "code": "UNAUTHORIZED" + } } - } - ] - } - ``` - { data-search-exclude } + ] + } + ``` + { data-search-exclude } -=== "404 Not found" + === "404 Not found" - Returned when the content type definition wasn't found + Returned when the content type definition wasn't found - ```json - { - "errors": [ - { - "message": "Not found", - "extensions": { - "code": "NOT_FOUND" + ```json + { + "errors": [ + { + "message": "Not found", + "extensions": { + "code": "NOT_FOUND" + } } - } - ] - } - ``` - { data-search-exclude } - + ] + } + ``` + { data-search-exclude } #### Step 2: Exploring Advanced Features Flotiq API offers various advanced features and functionalities to enhance your application. Here are a few examples: diff --git a/docs/CLI/excel-data-migration.md b/docs/CLI/excel-data-migration.md index 6baa1991..791b2d86 100644 --- a/docs/CLI/excel-data-migration.md +++ b/docs/CLI/excel-data-migration.md @@ -50,7 +50,7 @@ Command logs the following information: `--hideResults` or `--hr` - information about the export process will not appear in the console. -!!! Responses +!!! Response When successful: ``` { @@ -98,7 +98,7 @@ For every sheet in the workbook: `--hideResults` or `--hr` - information about the import process will not appear in the console. -!!! Responses +!!! Response When successful: ``` { From 73b9cfd4f1910951682a0fdd9e2483b750c94ba0 Mon Sep 17 00:00:00 2001 From: WHLukasz Date: Thu, 10 Oct 2024 14:19:35 +0200 Subject: [PATCH 3/3] clarify the type of field used for fetching single cto with graphql --- docs/API/graph-ql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/API/graph-ql.md b/docs/API/graph-ql.md index 4cb698a3..648a7fbf 100644 --- a/docs/API/graph-ql.md +++ b/docs/API/graph-ql.md @@ -175,7 +175,7 @@ Example Query in GraphQL language to get `id` and `title` for the product with i To do so, your content type definition has to have a text field with [unique property](../panel/content-types.md?h=unique#property-settings). This will allow you to query objects of that type using arguments: - - field: ``, + - field: ``, - value: `` !!! GraphQL query