Alexander Steiner
Home
Blog

Using Enums with GraphQL and Swift

Enums are a powerful language feature of Swift. They are more than a type-safe way of defining different states. But in this article, we'll concentrate on the basic enum functionality in Swift and we'll integrate them in a GraphQL API server which is based on Vapor. If you are new to GraphQL in combination with Vapor, I recommend reading my previous article where I go through the steps on how to build a GraphQL server with Swift and Vapor.

In this article, we'll extend the todo API example. Therefore we use a GraphQL Vapor template as a starting point. We want to build the feature of marking a todo as done or moving it to a "for later" list. To represent the different states of a todo we make use of enums. We'll save this state property with the rest of the information in a database and make them available through an extension to the GraphQL API that is already in place.

This Tutorial has been updated for Vapor 4 and the usage of Result Builders

Creating the project

So let's get started by creating a new Vapor project based on the GraphQL templated we build up in the previous article. Therefore we use the Vapor toolchain but instead of creating a project from the default template we specify the repository of the GraphQL template: vapor new todo-server --template=alexsteinerde/vapor-graphql-template

Please make sure, you have the GraphQLKit Version 2.1.0 as the dependency. Version 2.0.0 is missing some helper functions for enums.

.package(url: "https://github.com/alexsteinerde/graphql-kit.git", from: "2.1.0"), // Vapor Utilities

TodoState enum

Now we can add our enum which represents the different states our todo can be in: TodoState. As it belongs to the Todo class we can add it as a sub-enum. We let the enum conform to String so it's prepared to be Codable and also to CaseIterable which allows us to automatically infer all possible cases when registering it in our GraphQL schema later.

For more information about Fluent and enums, have a look at the documentation.

extension Todo {
    enum TodoState: String, Codable, CaseIterable {
        case open
        case done
        case forLater
    }
}

Extended Todo Model

We extend our existing Todo model to store the state as a property and also add support for saving the state to a Fluent database.

/// A single entry of a Todo list.
final class Todo: Model {
    ... other properties
    
    @Field(key: "state")
    var state: TodoState

    /// Creates a new `Todo`.
    init(id: UUID? = nil, title: String, state: TodoState = .open) {
        self.id = id
        self.title = title
        self.state = state
    }
}

We add the property state and add a new constructor parameter that can be pass in but is set to .open by default.

And we also need to update our migration structure:

struct MigrateTodos: Migration {
    func prepare(on database: Database) -> EventLoopFuture<Void> {
        return database.schema("todos")
            .id()
            .field("title", .string, .required)
            .field("state", .string, .required) // 1) NEW:  Add new field
            .create()
    }

    func revert(on database: Database) -> EventLoopFuture<Void> {
        return database.schema("todos").delete()
    }
}

By default, we use the SQLite Fluent database which stores data in-memory. If you want to use MySQL, PostgreSQL or other databases you can look up the requirements of a storable enum at the Vapor documentation or in the Vapor Discord channel.

Business Logic API

Next, we write the business logic that lets us change the state of a todo. To identify the todo we want to change we use the id. The id and the new state are our two arguments. They can be found in the struct ChangeTodoStateArguments.

extension TodoResolver {
    struct ChangeTodoStateArguments: Codable {
        let id: UUID
        let state: Todo.TodoState
    }
    
    func changeTodoState(request: Request, arguments: ChangeTodoStateArguments) throws -> EventLoopFuture<Todo> {
        Todo.find(arguments.id, on: request.db)
            .unwrap(or: Abort(.notFound))
            .map ({ (todo) -> Todo in
                todo.state = arguments.state
                return todo
            })
            .flatMap({
                $0.save(on: request.db)
                    .transform(to: $0)
            })
    }
}

The function changeTodoState accepts the current request to use for database operations and the arguments. It returns the updated Todo as a future. To update the todo we first search for the given id. If no entry is found we throw a notFound error. Otherwise, we replace the old state with the new one and save it to the database by calling .save(on: request.db).

Schema

Now let's modify our schema instance in the Schema.swift file. We need to add the enum type to our Schema (1). It must be defined before any other usage of the TodoState type! The Enum constructor normally needs an array of Values that represent the cases the enum has. But with GraphQLKit an extension to the type is provided that allows enums that conform to CaseIterable to be passed directly without a list of values to the constructor. Secondly, we add the new Field state to our Todo type (2). And to switch between states we add the new mutation changeTodoState at the end (3).

// Definition of our GraphQL schema.
let todoSchema = try! Schema<TodoResolver, Request> {
    Scalar(UUID.self)
    Enum(Todo.TodoState.self)

    // Todo type with it's fields
    Type(Todo.self) {
        Field("id", at: \.id)
        Field("title", at: \.title)
        Field("state", at: \.state) // 2) NEW: Todo state field
    }
    // We only have one single query: Getting all existing todos
    Query {
        Field("todos", at: TodoResolver.getAllTodos)
    }

    // Both mutations accept arguments.
    // First we define the name
    // and we pass the keypath to the field of the argument struct.
    Mutation {
        Field("createTodo", at: TodoResolver.createTodo) {
            Argument("title", at: \.title)
        }

        Field("deleteTodo", at: TodoResolver.deleteTodo) {
          Argument("id", at: \.id)
        }
        
        Field("changeTodoState", at: TodoResolver.changeTodoState) { // 3) NEW: Change Todo State API
            Argument("id", at: \.id)
            Argument("state", at: \.state)
        }
    }
}

Example Queries

Now that we have our API ready we can run the server and go to http://localhost:8080 to execute queries against our GraphQL API.

# Getting all todos with it's id, title and state
query GetAllTodos {
  todos {
    id
    title
    state
  }
}

# Creating a new todo sets the state to `open` by default
mutation CreateNewTodo {
  createTodo(title: "Test") {
    id
    title
    state
  }
}

# After creating a todo we can mark it as `done`.
# Or instead of `done` we could also pass `open` or `forLater` here.
mutation MarkTodoeAsDone {
  changeTodoState(id: "1b06a7bc-b542-41cf-8b2a-328943a5ce80", state: done) {
    id
    state
  }
}

Conclusion

This time we added enum functionality to GraphQL. We build on top of the previous template and the end result can be found in a separate GitHub repository.

What we haven't implemented is creating a new todo with a given state via GraphQL. But this isn't too complicated and doesn't require too many changes. Take it as a challenge and try implementing this by yourself and maybe you come up with some great results I haven't thought about yet.

What are other use cases you have when developing your APIs? Do you think GraphQL can be an advantage there? Let me know your thoughts on Twitter or via email.

Tagged with: