Standardisation of the gRPC apis

Hey guys, I would like to propose a standardisation of the definition of the gRPC apis.

Get

The request should contain the hash of the resource to get.
The response should be directly the resource definition.

rpc Get(GetResourceRequest) returns (definition.Resource) {}

message GetResourceRequest {
  string hash = 1;
}

Here is my pro and con to directly return the resource definition instead of a response message that contains it:

Pro

  1. Less proto definition. No need to create a other proto message
  2. Force to only returns the resource without any other data. If any data needs to be returned it’s either because the api is not well designed or a new type of api and resource need to be created.
  3. Reusability. Having to create the resource definition in the package protobuf/definition push to reuse the same definition for many APIs.

Con

  1. Less flexibility. Cannot add metadata on the returned ressource. But as said in point pro.2, it’s actually mean the api is poorly designed.

List

The request message should contained the possible and optional filter to apply. The request can be empty if no filter is implemented.
The response message should contain the resources as an array.

rpc List (ListResourcesRequest) returns (ListResourcesResponse) {}

message ListResourcesRequest {
  string possibleAndOptionalFilter = 1;
}

 message ListResourcesResponse {
  repeated definition.Resource resources = 1;
}

Create

The request should contain the necessary data to create the resource.
The response should only contain the calculated hash corresponding to the added resource.

EDIT #1:

rpc Create (CreateResourceRequest) returns (CreateResourceResponse) {}

message CreateResourceRequest {
  string allNecessaryDataToCreateTheResource = 1;
}

message CreateResourceResponse {
  string hash = 1;
}

Delete

I suggest that the delete API should be “send and forget”.
The request contains everything necessary but the response is empty.
Only the hash should be send in request.

rpc Delete (DeleteResourceRequest) returns (DeleteResourceResponse) {}

message DeleteResourceRequest {
  string hash = 1;
}

message DeleteResourceResponse {}

Update

I suggest that the update API should be “send and forget”.
The request contains everything necessary but the response is empty.
The hash and the data to update should be send in request.

rpc Update (UpdateResourceRequest) returns (UpdateResourceResponse) {}

message UpdateResourceRequest {
  string hash = 1;
  string dataToUpdate = 2;
}

message UpdateResourceResponse {}

Merge identical message

As you see, there is a few identical messages that only contain the resource’s hash:

  • GetResourceRequest
  • CreateResourceResponse
  • DeleteResourceRequest.

We could merge those message into one:

message ResourceIdentifier {
  string hash = 1;
}

I’m not sure it’s really necessary and actually useful. It will remove flexibility to add “flags” to the request (but do we actually want those?).


@core what do you think guys?

EDIT #1

Replaced:

rpc Create (definition.Resource) returns (CreateResourceResponse) {}

message CreateResourceResponse {
  string hash = 1;
}

By:

rpc Create (CreateResourceRequest) returns (CreateResourceResponse) {}

message CreateResourceRequest {
  string allNecessaryDataToCreateTheResource = 1;
}

message CreateResourceResponse {
  string hash = 1;
}

I prefer explicit XRequest & XResponse, otherwise it’s not possible to have the repeated types or metadata. this is not a bad api at all. same applied in the resfull api world

I like the idea of responses to return deleted resource, that way cli can use it to inform user after deletion, and it’s more functional. but not mandatory.

Updates must return the updated resource, always a good pattern, same applied in the resfull api world.

1 Like

As for me:

+ return resources for get

  • Merge identical messages - that might introduce some pbms in the future and I think it’s safer to split them.
  • List should return resources stream instead of one big object as caller might have ask about lots of objects.

But let’s not forget that api should be designed for functionalities and not strictly for following the rules.

This will be released in Engine v0.11