# GraphQL Request and Response Structure

GraphQL API is an alternative to a traditional REST API, but operates similarly. To execute a query, make a POST request to the GraphQL endpoint, available at `https://{MyDomainName}.my.salesforce.com/services/data/v{version}/graphql`.

Replace these values:

- `MyDomainName`: A custom subdomain specific to a Salesforce org. For example, `companyname` creates the URL `https://companyname.my.salesforce.com`.
- `version`: A Salesforce API version in the format XX.X. For example, 57.0.

For a collection of sample queries, connect to the [Salesforce Developer Postman Collection](/docs/platform/graphql/guide/get-started-postman.md).

For a deep dive into the types involved in the request and response, see the [API Reference](/docs/platform/graphql/references/graphql?meta=Summary).

## Request

The GraphQL request body has four parts. The `query` field contains the GraphQL query as a string. Optionally, use the `operationName` field to indicate which query to execute. Provide the `operationName` field if the query has multiple queries or mutations, to specify which query or mutation to execute. If the query defines any variables, include them as a map under the `variables` field. Finally, if the query uses extensions, include them as a map under the `extensions` field.

Here's a simple request to execute a query.

```json
{
  "query": "query accounts {
      uiapi {
          query {
              Account {
                  edges {
                      node {
                          Id
                          Name {
                              value
                          }
                      }
                  }
              }
          }
      }"
}
```

This request specifies that the `contacts` query is the one query executed of the two defined in the document.

```json
{
  "query": "query accounts {
      uiapi {
          query {
              Account {
                  edges {
                      node {
                          Id
                          Name {
                              value
                          }
                      }
                  }
              }
          }
      }
      query contacts {
          uiapi {
              query {
                  Contact {
                      edges {
                          node {
                              Id
                              Name {
                                  value
                              }
                          }
                      }
                  }
              }
          }"
  "operationName": "contacts"
}
```

This request includes argument values for variables defined in the query.

```json
{
    "query": "query accountById($id: ID) {
        uiapi {
            query {
                Account(where: {
                    Id: { eq: $id }
                }) {
                      edges {
                          node {
                              Id
                              Name {
                                  value
                              }
                          }
                      }
                  }
              }
          }",
    "variables": {
        "id": "001xx000003GYQxAA0"
    }
}
```

### Example Requests

If you're sending a request via curl or HTTP, send the query with your API access token in a JSON string.

```bash
curl  --location --request POST 'https://lng-dev-ed.my.salesforce.com/services/data/v57.0/graphql' \
-H 'Authorization: Bearer YourAccessToken' \
-H 'Content-Type: application/json' \
-d '{ "query": "query accounts { uiapi { query { Account { edges { node { Id \n Name { value } } } } } } }" }'
```

You can also use a JSON tool like [JQ](https://stedolan.github.io/jq/) to help transform or format your output.

```bash
curl  --location --request POST 'https://lng-dev-ed.my.salesforce.com/services/data/v57.0/graphql' \
-H 'Authorization: Bearer YourAccessToken' \
-H 'Content-Type: application/json' \
-d '{ "query": "query accounts { uiapi { query { Account { edges { node { Id \n Name { value } } } } } } }" }' \
| jq .
```

To send a request via a client like [Altair or Postman](/docs/platform/graphql/guide/get-started.md), pass in the query directly.

```sfdocs-code {"lang":"graphql", "title": "Query accounts using a client", "src": "" }
query AllAccounts {
    uiapi {
        query {
            Account {
                edges {
                    node {
                        Id
                        Name { value }
                    }
                }
            }
        }
    }
}
```

## Response

The response has a `data` section, an `errors` section, and an `extensions` section. The `data` section contains the response to the request query. The `errors` [section](/docs/platform/graphql/references/graphql?meta=type%3AGraphQLErrorRepresentation) includes errors that occur during the execution of the request. The `extensions` section includes extensions returned by the request.

```http
{
  "data": { ... },
  "errors": [ ... ],
  "extensions": { ... }
}
```

### Example Responses

If the request is successful, you receive a JSON blob like this.

```json
{
  "data": {
    "uiapi": {
      "query": {
        "Account": {
          "edges": [
            {
              "node": {
                "Id": "0011a000005slmbAAA",
                "Name": {
                  "value": "GenePoint"
                }
              }
            },
            {
              "node": {
                "Id": "0011a000005slmcAAA",
                "Name": {
                  "value": "United Oil & Gas, UK"
                }
              }
            },
            {
              "node": {
                "Id": "0011a000005slmeAAA",
                "Name": {
                  "value": "Edge Communications"
                }
              }
            }
          ]
        }
      }
    }
  },
  "errors": [],
  "extensions": {}
}
```

If the request fails, you receive a JSON blob like this.

```json
{
  "data": {},
  "errors": [
    {
      "extensions": {
        "ErrorType": "ValidationError"
      },
      "locations": [
        {
          "column": 7,
          "line": 4
        }
      ],
      "message": "Validation error of type FieldUndefined: Field 'Accounts' in type 'RecordQuery' is undefined @ 'uiapi/query/Accounts'",
      "paths": []
    }
  ],
  "extensions": {}
}
```

## See Also

[Status Codes and Error Responses](/docs/platform/graphql/guide/query-status.md)