Consider GraphQL for Discovery/Subscription APIs

Overview

As part of the design exercise for the discovery and subscription APIs, it was suggested that we consider GraphQL instead of REST.

To start the conversation, I’ve put together a candidate design for what a GraphQL API would look like.

You can see it in action here: discovery.in-the-cloud.dev

There this provides for essentially 3 entry points for discover in the RootQueryType

• providers - Search for human readable providers
• types - search for know events by ce-type
• search - open search against providers and types

This leads to other queries that narrow in on information to actually get the information needed to create a subscription.

• producer(provider:, type: )

Reasons to choose GraphQL

• Flexibility for representing the relationships we have
  • provider <-> type
  • {provider, type} -> producer
• allows for easy future expansion if we wanted to introduce source discovery (ce-source)
• Sever libraries available in many languages: https://graphql.org/code/
  • Client libraries available: https://graphql.org/code/#graphql-clients

Discovery Example

1. What providers to I have?

{
  providers{
    name
  }
}

which produces the results

{
  "data": {
    "providers": [
      {
        "name": "Cloud Storage"
      },
      {
        "name": "Cloud SQL Database"
      },
      {
        "name": "IOT Broker"
      },
      {
        "name": "GitHub"
      },
      {
        "name": "Other Cloud Storage"
      },
      {
        "name": "Cloud Pub/Sub System"
      }
    ]
  }
}

1. -or- perhaps I want to also see the event types available, and also narrow the providers down to things with “storage” in the name

{
  providers(matching: "storage") {
    name
    description
    types {
      name
    }
  }
}

Which would produce the results of

{
  "data": {
    "providers": [
      {
        "description": "Cloud Blob Storage",
        "name": "Cloud Storage",
        "types": [
          {
            "name": "com.storage.object.create"
          },
          {
            "name": "com.storage.object.delete"
          }
        ]
      },
      {
        "description": "A differe cloud blob storage",
        "name": "Other Cloud Storage",
        "types": [
          {
            "name": "com.storage.object.create"
          },
          {
            "name": "com.storage.object.delete"
          }
        ]
      }
    ]
  }
}

1. Given a provider and an event type, it is possible to narrow down into the details needed to create a subscription.

{
  producer(provider: "Cloud Storage", type: "com.storage.object.create") {
    dataSchema
    dataContentType
    subscriptionConfig {
      name
    }
    subscriptionEndpoint
    protocols
  }
}

which produces the results of

{
  "data": {
    "producer": [
      {
        "dataContentType": "application/json",
        "dataSchema": "https://schemas.in-the-cloud.dev/download/com.storage.object.create.json",
        "protocols": [
          "http"
        ],
        "subscriptionConfig": [
          {
            "name": "path"
          }
        ],
        "subscriptionEndpoint": "https://subscribe.events.broker/com.storage.object.create?provider=Cloud Storage"
      }
    ]
  }
}

[jskeet]

We’ve had a few items like this where we think they’re worth keeping track of but without keeping them open. Perhaps create a “backlog” label, apply that, then close?

[duglin]

Done - created “backlog” label. Let me know if you think other issues should get that label too. I’ll check the recently closed ones