In this blog post, I'll introduce GraphQL and explain how you can send and process network requests with a GraphQL query in Swift without third-party libraries.
Motivation
GraphQL as a query language makes it easier for clients to ask for exactly what they need from an API.
This has two significant advantages:
As an example, let's imagine that a client wants to get the following information from a GitHub repository
- the number of stars for a repository
- release information from a repository (only the two latest) and
- git tag information of a repository (only the two latest)
Three network calls are necessary to retrieve the following information from the GitHub REST API:
- GET https://api.github.com/repos /{owner}/{repo}
- GET https://api.github.com/repos /{owner}/{repo}/releases
- GET https://api.github.com/repos /{owner}/{repo}/tags
The REST API would also return other fields not requested by the client.
Only one network call is required when using GraphQL. The requested fields are expressed through the GraphQL query.
POST https://api.github.com/graphql
{
repository(owner: "MarcoEidinger", name: "SwiftPlantUML") {
stargazerCount
nameWithOwner
name
url
releases(orderBy: {direction: ASC, field: CREATED_AT}, last: 2) {
nodes {
isDraft
isLatest
isPrerelease
createdAt
tagName
}
}
refs(
refPrefix: "refs/tags/"
last: 2
orderBy: {field: TAG_COMMIT_DATE, direction: ASC}
) {
edges {
node {
name
target {
... on Commit {
committedDate
}
... on Tag {
tagger {
date
}
}
}
}
}
}
}
}
Example: GitHub GraphQL
If you want to learn more about GitHub's GrapQL API, you can download the latest version of the public schema from here. Better is to leverage the Explorer to get familiar with the query options.
Swift Coding
Swift's Foundation framework allows you to send an HTTP POST request (to a GraphQL endpoint). Use JSONEncoder to encode the GraphQL query and attach it to the request as its httpBody.
In this blog post, I wanted to explicitly demonstrate how to handle GraphQL without any library, although I probably would use a library (or build my own). Tools like Apollo iOS can provide a strongly-typed GraphQL client, which makes the query creation and parsing of the response easy and safe. However, such libraries may not offer the latest features you might hope for, e.g. Swift Modern Concurrency.
If you want to go without any third-party library, I recommend using QuickType.io to generate a Swift model from your expected GraphQL response.
Here are the generated types for the given example.
import Foundation
struct GitHubGraphQLResponse: Codable {
var data: DataClass?
}
struct DataClass: Codable {
var repository: Repository?
}
struct Repository: Codable {
var stargazerCount: Int?
var nameWithOwner, name: String?
var url: String?
var releases: Releases?
var refs: Refs?
}
struct Refs: Codable {
var edges: [Edge]?
}
struct Edge: Codable {
var node: EdgeNode?
}
struct EdgeNode: Codable {
var name: String?
var target: Target?
}
struct Target: Codable {
var committedDate: Date?
let tagger: Tagger?
}
struct Tagger: Codable {
let date: Date?
}
struct Releases: Codable {
var nodes: [NodeElement]?
}
struct NodeElement: Codable {
var isDraft, isLatest, isPrerelease: Bool?
var createdAt: Date?
var tagName: String?
}
Additionally, I like to create a helper Payload struct that can be used for any kind of GraphQL query.
struct Payload: Codable {
var variables: String = "{}"
var query: String
}
Here is a fully functional example of sending and processing a network request that queries one of my projects, SwiftPlantUML, with GraphQL.
import Foundation
func querySpecificRepositoryWithGraphQLQuery() async throws -> GitHubGraphQLResponse {
let username = "MarcoEidinger"
let pat = "ghp_y........."
let base64EncodedCredentials = "\(username):\(pat)".data(using: .utf8)!.base64EncodedString()
var request = URLRequest(url: URL(string: "https://api.github.com/graphql")!)
request.httpMethod = "POST"
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("Basic \(base64EncodedCredentials)", forHTTPHeaderField: "Authorization")
let query =
"""
{
repository(owner: "MarcoEidinger", name: "SwiftPlantUML") {
stargazerCount
nameWithOwner
name
url
releases(orderBy: {direction: ASC, field: CREATED_AT}, last: 2) {
nodes {
isDraft
isLatest
isPrerelease
createdAt
tagName
}
}
refs(
refPrefix: "refs/tags/"
last: 2
orderBy: {field: TAG_COMMIT_DATE, direction: ASC}
) {
edges {
node {
name
target {
... on Commit {
committedDate
}
... on Tag {
tagger {
date
}
}
}
}
}
}
}
}
"""
let payload = Payload(query: query)
let postData = try! JSONEncoder().encode(payload)
request.httpBody = postData
let response = try await URLSession.shared.data(for: request)
let jsonDecoder = JSONDecoder()
jsonDecoder.dateDecodingStrategy = .iso8601
let jsonData = response.0
let gitHubGraphQLResponse = try jsonDecoder.decode(GitHubGraphQLResponse.self, from: jsonData)
return gitHubGraphQLResponse
}
Adjust the values for variables username, pat, and query for your own example. Finally, you would need to replace GitHubGraphQLResponse.self with your response type.
Note: An authenticated user is needed to use GitHub's GraphQL API. The coding example shows how to use a personal access token, but you are better off leveraging OAuth2 for productive use.
