GraphQL API Schema

This page provides general information about GraphQL and the reference schema for Maildrop.

What's GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

Put another way, GraphQL is a modern, more structured and standardized way of querying APIs. Understanding the core GraphQL terms lets developers consume any GraphQL API without needing specialized knowledge about the API itself.

Here's a sample GraphQL query and response:

query PingSample {
    ping(message: "Hello, world!")
}

{"data":{"ping":"pong Hello, world!"}}

Why GraphQL and not REST?

Maildrop is using GraphQL for three primary reasons:

Give client developers freedom - rather than having a REST API that returns every piece of data on every request, GraphQL requests specify which pieces of data they need. This can greatly speed up data transfer and makes overall performance faster.
Easy ramp-up for existing GraphQL users - once a developer understands queries and mutations, and how to format them, every GraphQL API behaves exactly the same. The overall time to roll out a functional prototype using GraphQL is much faster than a traditional REST API.
Ability for developers to run multiple queries in one request - Rather than having multiple connections to multiple REST API endpoints, one GraphQL query can specify multiple pieces of data; for example, the maildrop.cc site requests the list of messages in a mailbox while also asking for the mailbox alias for that mailbox.

Which GraphQL library should I use?

Apollo is a very fully-featured library with support for Javascript/Typescript, Swift, and Kotlin. While it's certainly possible to write your own HTTP transport library to make GraphQL queries and mutations, using the Apollo library takes care of otherwise-time-consuming tasks such as marshaling/un-marshaling JSON, caching data locally, transforming data as it appears, handling data refetching, and so on. Apollo will speed up development times when dealing with any GraphQL API.

The full GraphQL schema for Maildrop

Taken directly from the source code for the API server:

export const schema = `#graphql
    type Message {
        id: String
        ip: String
        helo: String
        date: String
        mailfrom: String
        rcptto: [String]
        headerfrom: String
        subject: String
        data: String
        html: String
    }
    type Statistics {
        blocked: Int
        saved: Int
    }
    type Query {
        ping(message: String): String
        inbox(mailbox: String!): [Message]
        message(mailbox: String!, id: String!): Message
        altinbox(mailbox: String!): String
        statistics: Statistics
        status: String
    }
    type Mutation {
        delete(mailbox: String!, id: String!): Boolean
    }
`;