What is GraphQL and why should you ditch your beloved RESTful API for it?

1. GraphQL
The best thing to happen to the internet since cats.

2. About Me

3. About You

4. Let’s talk about RESTful APIs

6. Perfect endpoints
Everything is an entity
Routes are clear and defined
HTTP verbs and codes describe interaction
GET /products
POST /products
GET /products/4063745
PUT /products/4063745

7. Realistic endpoints
Entities are grow and change
Multiple requests for a single UI view
Routes get specialized and custom
Query parameters change responses
HTTP verbs and codes get creative
Actions start to get swept... somewhere
GET /products
GET /products?mobile=true
POST /products
POST /products?season=winter
GET /products/406
GET /products/406/images
PUT /products/406/upload-photo
POST /calc-ship?id=406&zip=33620

8. Real data happens

9. Perfect data sources
Everything lives in one database
Every table and entity match your app logic
Use a CDN to host large files and images
Integrate with great 3rd-party APIs like Stripe

10. Realistic data sources
Multiple, different databases
Databases that need love
First- and third-party APIs of varying quality
Legacy systems that haven’t been updated
JSON, Websockets, XML, CSVs

11. Real data sources happen

12. Coping with lots of data
Have massive, slow, and mostly unused responses
Create multiple versions of an endpoint for different scenarios
Use query parameter voodoo to save resources
Have a ton of conditional logic in the API to wrangle everything together

13. How about them docs tho?

14. Documentation is hard
Tools like Swagger and APIDoc are great but take effort to maintain
Framework goodies like Django Rest assume you don’t deviate
Custom docs site somewhere like Confluence is not fun to update
End result: Incomplete, out of date, or non-existent docs

16. Real business decisions happen

17. Versioning is hard
Maintaining backwards compatibility and support
Updating clients and tools ( unmaintained? )
Version the whole API or individual endpoints
Code and hardware can bloat quickly
Don’t forget the docs

18. How much insight is there?

19. Monitoring is hard ( and expensive )
Monitoring services like NewRelic
Lots of disparate and expensive data to connect
Lowest-level resolution is the request
Which parts of the response are most used or unused?

20. There is a better way

22. Data first, organization second
A single endpoint returns all data
A typed schema organizes all data into entities
Entities can span many data sources
The APIs job is to create a web of data

23. Data on demand
Request as much or as little data as needed
Multiple resources in a single request
No bloated responses
Format data on the server
No need to create custom endpoints
{
product {
id
name
images: {
url: ( size: "xs" )
altText
}
price: ( format: "usd" )
}
promotion {
id
name
}
}

24. Versions are dead, long live versioning
No need to version the whole API
Easily add new fields to entities
Ability to deprecate the old fields
@deprecated notifies requestors
Facebook famously still supports the 3GS
{
product {
id: ID
name: String
sizes: [ String ] @deprecated
availableSizes: [ ShirtSize ]
}
}

25. APIs that document themselves
A typed schema can generate good docs
Support for comments in the schema
GraphiQL lets you explore with your own data
GraphiQL has autocomplete and docs
3rd-party tools can create visuals and utilities

26. Monitor every detail
See how each field impacts performance
See which fields are used ( and how often )
and remove unused fields worry-free

27. Awesome resources
0-60 Full-stack tutorial
https://www.howtographql.com
Official docs and guides
http://graphql.org
Serverles GraphQL API as a service
https://www.graph.cool
The best full-stack tools and docs for GraphQL
http://dev.apollodata.com

28. ¡ Gracias !
Charles V Burgess
Senior Developer @ Perch Security
GitHub: cvburgess
Web: cvburgess.com
Email: consulting@cvburgess.com
LinkedIn: cvburgess