# GraphQL

> An API language where the app asks for exactly the fields it needs, in one request.

- Level: Advanced
- Topics: Software
- URL: https://tidbit.legios.com.ar/graphql/
- In Spanish: [GraphQL](https://tidbit.legios.com.ar/es/graphql/)

**GraphQL** is a way of building APIs in which the client writes a **query** describing the exact data it wants, and the server answers with JSON in that same shape. It was created at Facebook in 2012 to feed its mobile apps, released publicly in 2015, and is now maintained by the GraphQL Foundation, part of the Linux Foundation.

Compare it with a REST API. To show a profile screen, a REST app might call `/users/7`, then `/users/7/orders`, then `/orders/91/items`, and receive many fields it never shows. With GraphQL it sends one request to a single endpoint, usually `/graphql`, saying "user 7: name, and the last two orders with their totals", and gets just that. This avoids **over-fetching** (too much data) and **under-fetching** (too many round trips), which matters on slow mobile connections.

Behind the endpoint sits a **schema**: a typed description of every object and field the API offers, which tools use to autocomplete and validate queries before they run. Each field is filled in by a small function called a **resolver**, which can read from a database, a REST service or anything else. The flexibility has costs: caching is harder than with plain URLs, and a careless query can ask for so much nested data that it overloads the server, so production APIs limit query depth and cost.

## An analogy

REST is a set menu: each dish comes as the kitchen decided. GraphQL is ordering à la carte from a printed list of every ingredient: you get exactly what you asked for, but the kitchen has to watch out for absurd orders.

## Keep in mind

- One endpoint; the client's query decides the shape of the answer.
- A typed schema lists everything that can be asked for.
- Avoids fetching too much or making many round trips.
- Harder to cache and needs limits against very expensive queries.

## Go deeper

- [Introduction to GraphQL (official site)](https://graphql.org/learn/)
- [What is GraphQL? (AWS)](https://aws.amazon.com/graphql/)
- [GraphQL on Wikipedia](https://en.wikipedia.org/wiki/GraphQL)

## Related terms

- [API](https://tidbit.legios.com.ar/api/): The menu of things one program lets another program ask for.
- [Server](https://tidbit.legios.com.ar/server/): A computer whose job is to answer requests from other computers, all day, every day.
- [JSON](https://tidbit.legios.com.ar/json/): The plain-text format programs use to hand each other structured data.
- [Meta](https://tidbit.legios.com.ar/meta/): The company behind Facebook, Instagram and WhatsApp, paid for by advertising.
- [Linux](https://tidbit.legios.com.ar/linux/): A free, open source operating system that runs most of the internet's servers.
- [REST API](https://tidbit.legios.com.ar/rest-api/): The most common style of web API: things have URLs and you act on them with HTTP verbs.
- [Database schema](https://tidbit.legios.com.ar/database-schema/): The blueprint of a database: which tables exist, their columns and how they connect.
- [Database](https://tidbit.legios.com.ar/database/): An organized store of data that programs can search and update safely.