# General / GraphQL Getting Started # GraphQL Introduction GraphQL is an API query language originally developed by Facebook. We've elected to develop our API using GraphQL as much of the data in Shopfront is related to each other and it allows us to easily add new features without worrying about breaking existing applications. If you've never used GraphQL before, we would highly suggest going through the official [GraphQL learning resources](https://graphql.org/learn/). This will provide you with the most information and a full list of features that you can use with GraphQL, but we've compiled a quick basics here. > Prefer to explore the schema directly? [Download the full GraphQL schema (SDL)](/developer/graphql/shopfront.graphql). ## Getting Started > Before you get started with GraphQL, make sure you authenticate your > application. [More information can be found here](/documentation/General/Authentication). GraphQL essentially works the same was that any REST or SOAP API does, however instead of multiple having multiple URLs (like REST), you instead have a single endpoint (`/graphql`) (similar to SOAP). Through this endpoint you can query any object or perform a mutation. If you are getting data from Shopfront, that request is called a query. If you are sending data to / updating data in Shopfront, that request is called a mutation. The best way to learn is typically to do, so let's make a request to our API, we'll retrieve a list of all the Users for our vendor (not sure how to read this? [The MDN web docs has a good set of instructions](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages)): ```http POST /api/v2/graphql HTTP/1.1 Host: example.onshopfront.com Authorization: Bearer 123abc Content-Type: application/json Accept: application/json { "query": "{\n users {\n id,\n name\n }\n}" } ``` Let's go through this request. We'll start off at the top and work our way down: ```http POST /api/v2/graphql HTTP/1.1 Host: example.onshopfront.com ``` This is just making a standard `POST` request to the URL `https://example.onshopfront.com/api/v2/graphql`. You should replace `example` with your store URL. > You might have noticed we're using a POST request even through we > are retrieving data (typically a GET request). This is because GraphQL > requests can end up being quite long and sending it all through a URL > can lead to issues. The Shopfront API supports making GraphQL requests > using any request method, but we highly suggest using POST for all > requests. ```http Authorization: Bearer 123abc ``` This is the authorisation bearer token header that you will have been provided after completing the [authentication](/documentation/General/Authentication). ```http Content-Type: application/json ``` The `Content-Type` header specifies what type of content we're providing, in this case it's `JSON`. We also support using the `application/graphql` content type, however some client applications don't recognise it and it gets handled slightly differently, so we recommend sticking with the standard `application/json`. ```http Accept: application/json ``` This lets the server know what sort of data you would like returned, we currently only support returning `JSON` so you're safe to leave it off if you'd like. ```json { "query": "{\n users {\n id,\n name\n }\n}" } ``` This is where things start to get interesting, this is simply `JSON` with a key called `query` which (surprise) contains the GraphQL query, let's format it and have a look: ```graphql { users { id, name } } ``` This is a really simple query that gets all the users and returns their id and name. After performing the query you'll receive a response that looks something like this: ```json { "data": { "users": [ { "id": "123abc", "name": "User #1" }, { "id": "321cba", "name": "User #2" } ] } } ``` That's all there really is to it. If there was an error during your query you'll have an `error` key in the returned data (for example): ```json { "data": { "users": null }, "errors": [{ "message": "Something bad happened" }] } ``` If you need to pass [variables](https://graphql.org/learn/queries/#variables) to the server, you can add a `variables` key to the `JSON` that you send to the server. Now that you've got the basics under control, it's time to learn some more at the official [GraphQL website](https://graphql.org) or jump into developing your application with our API. ## Interfaces & Unions Some fields can return one of several different types of object - these are represented in our schema as GraphQL [Interfaces](https://graphql.org/learn/schema/#interfaces) or [Unions](https://graphql.org/learn/schema/#union-types). Because the exact type being returned isn't known ahead of time, you need to use an "inline fragment" (`... on TypeName`) to request fields that only exist on one of the possible types. As an example, the `item` field on a sale's line items ([SaleItem](/documentation/Objects/Sales#SaleItem)) can be a [Product](/documentation/Objects/Products#Product), [GiftCard](/documentation/Objects/Gift%20Cards#GiftCard), [EnterpriseGiftCard](/documentation/Objects/Gift%20Cards#EnterpriseGiftCard) or [Surcharge](/documentation/Objects/Sales#Surcharge). To request fields specific to one of these types, wrap them in an inline fragment for that type: ```graphql { sale(id: "123abc") { items { id, item { id, ... on Product { name }, ... on GiftCard { code, currentAmount } } } } } ``` Fields declared directly on the Interface itself (like `id` above, which is declared by `SellableInterface`) can be requested directly, without an inline fragment - a field only qualifies for this if it's declared on the Interface, not merely because every concrete type happens to implement a field with the same name. Union types don't declare any fields of their own, so every field on a Union must be requested through an inline fragment. Fields specific to a single type must be wrapped in `... on TypeName { }` - if the object returned isn't of that type, those fields are simply omitted from the response. > You can include inline fragments for as many of the possible types as you like within the same query - only the > fragment matching the actual returned type will be populated. ## Field-Level Validation Shopfront supports performing field-level validation on inputs before attempting to process the query / mutation. When using a field that supports field-level validation, your input will be checked during the parsing stage of the request. If your input fails validation, an error will be returned in the `errors` array with the message containing the issue. Fields that support validation can be found throughout the documentation with each field documenting the rules it follows. > Currently this feature is opt-in only, to enable it, please set the `X-GraphQL-Validate-Variables` header to `true`. > This will become the default in the future.