Consider GraphQL over REST API

[Gozala]

Simplicity of REST API is great until:

1. Responses are large enough that getting only subsets becomes important.
2. Round-trips start to matter and some batching strategy is necessary.

Both lead to custom & non-composable solutions. For these reasons I would like to propose to consider https://graphql.org/ based API because:

1. You can query exactly what application needs / expects.
2. All operations are composeable and can be bundled into single request as necessary.
3. There is great tooling available for it.

[Gozala]

It is also worth considering how IPLD selectors fit or whether they could be a better solution than REST or / and GraphQL

[Gozala]

E.g. #1 is perfect example of needing to batch which GraphQL supports out of the box.

[lidel]

Would be good to run this idea by (a) Pinning Services (b) go-ipfs/js-ipfs

Quick take: In this specific domain (simple CRUD for managing pins) I don't believe there will be use case for mixing operations (any examples?), but I agree that batching status checks would be useful (#1). Also, pagination is missing from v0.0.1 of the spec – filled #12 for tracking that separately.

The old thread includes some feedback from @bonedaddy about representing this API over gRPC (Temporal looked into using go-swagger + grpc-gateway). I see people were successful with querying graphQL API over gRPC, but it is hard for me to tell if it makes things easier or harder for non-HTTP representations – are there any case studies we could look at?

[Gozala]

Would be good to run this idea by (a) Pinning Services (b) go-ipfs/js-ipfs

I think there are some relevant questions asked here #2 (comment)

Quick take: In this specific domain (simple CRUD for managing pins) I don't believe there will be use case for mixing operations (any examples?), but I agree that batching status checks would be useful (#1). Also, pagination is missing from v0.0.1 of the spec – filled #12 for tracking that separately.

Once scheduler is introduced into the system batching of queued operations becomes relevant. For instance once node goes offline it may accumulate bunch of pin, delete, maybe even status requests and ability to fulfill them in a single request would be fairly convenient. However if each operation allowed batching of sorts win probably will be negligible, however nice thing about GraphQL is that it's all composable so you get batching for free with an ability to query specific fields.

The old thread includes some feedback from @bonedaddy about representing this API over gRPC (Temporal looked into using go-swagger + grpc-gateway). I see people were successful with querying graphQL API over gRPC

I'm not familiar with gRPC and from a glance I do not really see a reason for creating gRPC layer just to add GraphQL over it, that is unless system already had a gRPC layer and GraphQL introduced a querying mechanism.

but it is hard for me to tell if it makes things easier or harder for non-HTTP representations – are there any case studies we could look at?

There are some case studies here https://www.graphql.com/case-studies/
I also have good experience building both GraphQL server and client, would not have raised this otherwise.

Could you elaborate on what you mean by "easier or harder for harder for non-HTTP representations"

GraphQL services are typically served over HTTP, that is not strictly necessary but I suspect pool of libraries to use with other transports to be smaller.