Bindings

[chriskapp]

Currently TypeAPI is used to describe REST APIs for example:

{
  "operations": {
    "getMessage": {
      "description": "Returns a hello world message",
      "method": "GET",
      "path": "/hello/world",
      "return": {
        "schema": {
          "$ref": "Hello_World"
        }
      }
    }
  },
  "definitions": {
    "Hello_World": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

in this case method and path are HTTP specific (or we could call it also REST specific) bindings. We could envision a future with TypeAPI where we not only describe REST APIs but also i.e. GraphQL endpoints while still generating the same client SDKs but providing a way to exchange the underlying transport technology. To enable this we would need to abstract those bindings, the example above could be written i.e.

{
  "operations": {
    "getMessage": {
      "description": "Returns a hello world message",
      "http:method": "GET",
      "http:path": "/hello/world",
      "return": {
        "schema": {
          "$ref": "Hello_World"
        }
      }
    }
  },
  "definitions": {
    "Hello_World": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

A GraphQL version could be written as:

{
  "operations": {
    "getMessage": {
      "description": "Returns a hello world message",
      "graphql:query": "{ message }",
      "return": {
        "schema": {
          "$ref": "Hello_World"
        }
      }
    }
  },
  "definitions": {
    "Hello_World": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

with this idea we could also imagine many different bindings like RPC (GRPC/Thrift/JsonRPC) or maybe also MessageQueue systems or maybe also plain SQL. Through this we could achieve some sort of technology independency this means we could change the underlying technology and the SDK user still uses the same API. While this sounds pretty ambitious it could be a real game changer for clients consuming a specific backend, since then you dont need to rewrite you client in case your backend technology changes.

We still need to think about some topics i.e. like authentication. Currently a user simply provides a specific authorization type regarding REST i.e. Bearer Token or Basic Auth, for GraphQL this still might work but for other bindings like GRPC or a message queue system it would be problematic. Also would it be possible to generate a client where each operation uses a different binding, in this case the client SDK needs the fitting authorization for every binding.