The document is a practical guide on API management for GraphQL, detailing its advantages over REST, including efficient querying and real-time subscriptions. It discusses key topics such as authentication, authorization, rate-limiting, and analytics relevant to GraphQL API management. The guide emphasizes the importance of security and performance considerations while implementing GraphQL APIs.

1. A practical guide to
API Management for GraphQL
June 30, 2020

2. Hello!
Bhathiya Jayasekara
Senior Technical Lead, WSO2
bhathiya@wso2.com

3. ● Introduction to GraphQL
● REST vs GraphQL
● Exposing GraphQL services as Managed APIs
⦿ Authentication
⦿ Authorization
⦿ Rate-Limiting
⦿ Analytics
● API Management for GraphQL demo
What’s covered?
3

4. What’s GraphQL?

5. ● A query language for your APIs.
● Gives what you request, nothing more and nothing less.
● Ability to make API calls more efficient, flexible, and developer-friendly.
● GraphQL specification is an SDL (Schema Definition Language).
● Created by Facebook in 2012 and released for open-source in 2015.
● Served over HTTP via a single endpoint.
● Specification - https://spec.graphql.org/June2018/
● Reference Implementation - https://github.com/graphql/graphql-js
● Implementations in many languages - https://graphql.org/code/
GraphQL
5

6. Example: Product-Management Service
6
Retailer
Id: ID
Name: String
Customer
Id: ID
Name: String
Product
Id: ID
Name: String
Category: enum (
CLOTHING
FOOTWEAR
COSMETICS
)
1
r
1 m
n n

7. ● Defines the capabilities of an API
● All the types are exposed in an API, written
down in a language called GraphQL Schema
Definition Language
● Contract between the server and the client.
Once it is defined, both sides are aware of
the data structure
● Query, Mutation, and Subscription root types
7
Type System

8. 8
GraphQL Query

9. 9
GraphQL Mutation

10. 10
GraphQL Subscription
● GraphQL subscriptions allow you to be notified in real-time of changes to your
data.
● Usually implemented with WebSockets or similar technologies.
● Eg: In the Product-Management service, a retailer will be notified whenever a
new Customer node is created.

11. REST vs GraphQL

12. REST API Call 1
Fetch a list of all products.
GET /products
12
Example: The retailer wants to know the list of customers who ordered a
particular product.

13. REST API Call 2
Fetch the list of customer IDs of a
particular product.
GET /products/{id}/customers
13
REST API Call 3...n
Fetch particular customer details by
sending their IDs one by one.
For (each customer) {
GET /products/{id}/customers/{id}
}

14. GraphQL API Call
Returns the details of a list of
customers of a particular product with
just a single query.
14

15. ● Pros
⦿ No more over-fetching or under-fetching
⦿ Single API call data fetching
⦿ High performance in data fetching networks
⦿ Versionless API evolution
● Cons
⦿ Not good for complex queries
- Slow down performance and kill the efficiency of applications
⦿ No support for HTTP caching
⦿ Overkill for smaller apps
⦿ No support for file uploads
GraphQL: Pros and Cons - Compared to REST
15

16. API Management for GraphQL

17. ● Authentication
● Role based access control (Authorization)
● Rate limit API traffic
● Detect and block malicious content
● Analytics
Why API Management?
17

18. Authentication

19. ● APIs are mostly exposed to external users.
● Security plays a major role at this point as it is crucial to ensure that the users
who access the API operations are authentic.
● However, there can be certain API functionalities they are exposed to the
public, giving access to anyone without needing to authenticate with the
system.
Authentication
19

20. Solution:
REST
GET /products
- Authentication OFF
GET /products/{id}/customers
- Authentication ON
GraphQL
?
20
Example requirement:
1. Allow getting product list without a token
2. Don’t allow getting customers of a product without a token

21. {
product(id: "2") {
id
name
}
}
- The `product` operation is allowed
without a token
Authentication: GraphQL
21
{
product(id: "2") {
id
name
customer {
name
id
}
}
}
- The `customer` operation is NOT allowed
without a token

22. Authorization

23. ● Certain API functionalities may need to be accessed by only a subset of users
in the user base.
● For such functionalities, only the authorized parties should have access.
● Typically done with OAuth2 scopes.
Authorization
23

24. Solution:
REST
● POST /products
- Retailer scope attached
● Decided based on the URL
GraphQL
● Mutation operation “addProduct”
- Retailer scope attached
● Decided based on the payload
24
Example requirement:
1. Don’t allow adding products for non-retailers
2. Allow adding products only for retailers

25. Rate limiting

26. ● There is only a certain amount of load the API backends can handle at a given
time.
● Can be a part of business plans related to API monetization too.
Rate Limiting
26
REST
● Usually, applied in the form of
TPS/TPM etc.
● Different resources typically have
different rate limit policies.
GraphQL
● TPS/TPM form is not adequate.
● Should be decided based on the
payload too.
● Need more dimensions for the limits
- Query Depth Analysis
- Query Complexity Analysis

27. ● Query depth can be infinite and cyclic.
● Too expensive for the backend
servers.
● Solution: Depth Limit
GraphQL: Query Depth Analysis
27

28. ● Query depth limit may not be
adequate
● The cost of fetching nodes at
different levels can be different
● Solution: Complexity Limit
GraphQL: Query Complexity Analysis
28

29. ● No standard way to calculate
● Different groups follow different approaches
GraphQL: Query Complexity Calculation
29
Example rule 1
● No arguments => multiply by 1
Example rule 2
● Multiply by argument value

30. Analytics

31. ● Helps you understand how your APIs are being used.
● Business analytics and operational analytics
● REST APIs Analytics at resource level
● GraphQL Analytics at operation level
Analytics
31

32. Demo

33. Question Time!
33

34. wso2.com
Thanks!